Tillwire Read the guide
API reference

Shipping. 16 operations.

16 of them work. Each needs a bearer token with its scope. All operations.

Operations

POST/api/v1/shipping/zonesshipping.add-zoneshipping.write

Parameters

Idempotency-KeyheaderstringSee common parameters

Errors: 401, 403, 405, 409, 413, 422, 429

curl -X POST -H "Authorization: Bearer $TOKEN" https://yourshop.example/api/v1/shipping/zones

GET/api/v1/shipping/connectors/{connector}/servicesshipping.connector-servicesshipping.read

Parameters

connectorpathstring
connectorpathstring

Errors: 401, 403, 404, 405, 422, 429

curl -X GET -H "Authorization: Bearer $TOKEN" https://yourshop.example/api/v1/shipping/connectors/{connector}/services

GET/api/v1/shipping/connectorsshipping.connectorsshipping.read

Errors: 401, 403, 405, 422, 429

curl -X GET -H "Authorization: Bearer $TOKEN" https://yourshop.example/api/v1/shipping/connectors

GET/api/v1/shipping/couriersshipping.couriersshipping.read

Errors: 401, 403, 405, 422, 429

curl -X GET -H "Authorization: Bearer $TOKEN" https://yourshop.example/api/v1/shipping/couriers

POST/api/v1/shipping/desk-quoteshipping.desk-quoteshipping.read

Parameters

Idempotency-KeyheaderstringSee common parameters

Request body

DeskQuoteRequest

Answer

DeskQuote

Errors: 401, 403, 405, 409, 413, 422, 429

curl -X POST -H "Authorization: Bearer $TOKEN" https://yourshop.example/api/v1/shipping/desk-quote

POST/api/v1/shipping/quotesshipping.keep-quoteshipping.write

Parameters

Idempotency-KeyheaderstringSee common parameters

Request body

KeepQuoteRequest

Answer

KeptQuote

Errors: 401, 403, 405, 409, 413, 422, 429

curl -X POST -H "Authorization: Bearer $TOKEN" https://yourshop.example/api/v1/shipping/quotes

GET/api/v1/shipping/quotes/{id}shipping.quoteshipping.read

Parameters

idpathstring
idpathstring

Answer

KeptQuote

Errors: 401, 403, 404, 405, 422, 429

curl -X GET -H "Authorization: Bearer $TOKEN" https://yourshop.example/api/v1/shipping/quotes/{id}

POST/api/v1/shipping/quotes/{id}/againshipping.quote-againshipping.write

Parameters

idpathstring
idpathstring
Idempotency-KeyheaderstringSee common parameters

Answer

KeptQuote

Errors: 401, 403, 404, 405, 409, 422, 429

curl -X POST -H "Authorization: Bearer $TOKEN" https://yourshop.example/api/v1/shipping/quotes/{id}/again

GET/api/v1/shipping/quotesshipping.quotesshipping.read

Parameters

afterqueryintegerThe id to go on after: the page's next; none for the newest.
limitqueryintegerHow many quotes, at most 100; 50 when left out.
activequerybooleantrue: only the quotes not ordered and not expired now.
line1querystringThe street address the quotes must fit; with the other address fields.
line2querystringThe unit, complex or building the quotes must fit.
suburbquerystringThe suburb the quotes must fit.
cityquerystringThe city or town the quotes must fit.
postal_codequerystringThe postal code the quotes must fit.
provincequerystringThe province the quotes must fit.
countryquerystringThe country's ISO 3166-1 alpha-2 code the quotes must fit.

Errors: 401, 403, 405, 422, 429

curl -X GET -H "Authorization: Bearer $TOKEN" https://yourshop.example/api/v1/shipping/quotes

POST/api/v1/shipping/zones/{id}/removeshipping.remove-zoneshipping.write

Parameters

idpathstring
idpathstring
Idempotency-KeyheaderstringSee common parameters

Errors: 401, 403, 404, 405, 409, 413, 422, 429

curl -X POST -H "Authorization: Bearer $TOKEN" https://yourshop.example/api/v1/shipping/zones/{id}/remove

POST/api/v1/shipping/couriersshipping.save-couriersshipping.write

Parameters

Idempotency-KeyheaderstringSee common parameters

Errors: 401, 403, 405, 409, 413, 422, 429

curl -X POST -H "Authorization: Bearer $TOKEN" https://yourshop.example/api/v1/shipping/couriers

POST/api/v1/shipping/boxesshipping.set-boxesshipping.write

Parameters

Idempotency-KeyheaderstringSee common parameters

Errors: 401, 403, 405, 409, 413, 422, 429

curl -X POST -H "Authorization: Bearer $TOKEN" https://yourshop.example/api/v1/shipping/boxes

POST/api/v1/shipping/optionsshipping.set-optionsshipping.write

Parameters

Idempotency-KeyheaderstringSee common parameters

Errors: 401, 403, 405, 409, 413, 422, 429

curl -X POST -H "Authorization: Bearer $TOKEN" https://yourshop.example/api/v1/shipping/options

POST/api/v1/shipping/zones/{id}shipping.set-zoneshipping.write

Parameters

idpathstring
idpathstring
Idempotency-KeyheaderstringSee common parameters

Errors: 401, 403, 404, 405, 409, 413, 422, 429

curl -X POST -H "Authorization: Bearer $TOKEN" https://yourshop.example/api/v1/shipping/zones/{id}

GET/api/v1/shipping/connectors/{connector}/test-quoteshipping.test-quoteshipping.read

Parameters

connectorpathstring
connectorpathstring
postal_codequerystringThe postal code the quote is asked to; with every address field left out, the sample address (12 Long Street, Cape Town, 8001).
cityquerystringThe city or town.
suburbquerystringThe suburb.
provincequerystringThe province.
line1querystringThe street address.
countryquerystringThe country's ISO 3166-1 alpha-2 code; ZA when left out.
weight_gqueryintegerThe parcel's weight in grams, 1 to 100000; the card's default parcel's when left out.

Answer

TestQuote

Errors: 401, 403, 404, 405, 422, 429

curl -X GET -H "Authorization: Bearer $TOKEN" https://yourshop.example/api/v1/shipping/connectors/{connector}/test-quote

GET/api/v1/shipping/zonesshipping.zonesshipping.read

Errors: 401, 403, 405, 422, 429

curl -X GET -H "Authorization: Bearer $TOKEN" https://yourshop.example/api/v1/shipping/zones

Schemas 43

Address

Address is a postal address in its fields and on one line: the domain's address, which the store's own address will take when the operations give store details.

cityrequiredstring
countryrequiredstring
country_namerequiredstring
linesrequiredarray of string
postal_coderequiredstring
provincerequiredstring
suburbrequiredstring
textrequiredstring
Connector

Connector is one courier connector: its name, as a setting names it; the name a person reads; the one currency it prices in ("" for any); and its declared capabilities, by their stable names, such as rates.checkout or deliver.door. /admin offers only the switches they allow. demo (version 6, additive) says a demo connector: it calls no one, needs no key, takes a carrier name, and runs only in a store that takes no real money.

answeredrequiredboolean
answered_capabilitiesarray of string
capabilitiesrequiredarray of string
currencyrequiredstring
declared_capabilitiesarray of string
demorequiredboolean
display_namerequiredstring
insures_alwaysrequiredboolean
namerequiredstring
outside_capabilitiesarray of string
ConnectorService

ConnectorService is one service of a connector to pick from: its code, which the courier settings' services name; its name and carrier ("" for one not in the sample); the kind of delivery its sample rate was (door, pickup_point, locker, in_store) and its sample price, the cheapest of its rates, the courier's, before the store's markup, both absent for one the connector's own list gave or one not in the sample; whether the card chooses it; and whether the list or the sample gave it.

carrierrequiredstring
chosenrequiredboolean
coderequiredstring
in_samplerequiredboolean
kindstring
namerequiredstring
sample_priceMoney
ConnectorServices

ConnectorServices are the services a connector of the store's set can offer, for the owner to choose the ones the checkout offers (courier curation A; version 6, additive): the connector's name and its name for people; its services, one per code; whether the connector's own list gave them (listed) or one test quote did (from the store's address to the sample address, with no service filter and no markup; Bob Go's checkout-rate names are the account's, so the quote lists them); and how long the courier took. Each service says whether the card's services choose it, and whether the list or the sample gave it: a code the card chose that neither gave is listed too, not in the sample (a sample to one place may miss a service offered elsewhere), so a save never drops it. With nothing from the courier, reason says why, as a test quote's not_asked does (no_collection_address, no_connection), or "failed" or "slow", and words in the test quote's words. Each call counts against the caller's test quotes (10 a minute, 429). It books nothing and writes nothing; the owner saves the codes chosen as the connector's services in the courier settings (EnabledConnector).

connectorrequiredstring
display_namerequiredstring
listedrequiredboolean
morestring
not_listedstring
reasonstring
servicesrequiredarray of ConnectorService
took_msrequiredinteger
wordsstring
Connectors

Connectors are the courier connectors the engine has, by name.

connectorsrequiredarray of Connector
CourierCollection

CourierCollection is a card's collection hours (collection,; version 6, additive): the hours the store is ready between and the cut-off, each HH:MM in the store's time zone, "" for the engine's default (08:00, 16:00 and 12:00). The window is 2 hours at least; a card whose connector does not declare collection takes none. A booking made before the cut-off asks for today, after it for the next working day.

afterrequiredstring
beforerequiredstring
cut_offrequiredstring
CourierHealth

CourierHealth is the health of one enabled connector (version 6, additive), for the Store health row ("Courier: Bob Go, sandbox"): its name, its name for people and its environment (sandbox or production); whether it can be checked; whether its last check answered, where it asked and when (checked_at null until the first check after the start); the failure of the last check in words ("" while it answered); the last failure since the start and when, kept after a later check that answered; and, for a connector that notifies (track.notify), the state of the engine's own notification subscription at the courier: "" fine or not read, "missing" (none delivers to the store), "inactive" (the courier turned it off: Bob Go does after three days of failures), "failing" (its deliveries fail since subscription_since, as they do while the store's webhook secret is not the courier's), or "unread" (the courier's list could not be read).

checkedrequiredboolean
checked_atrequiredstring (date-time)
display_namerequiredstring
environmentrequiredstring
failurestring
last_failurestring
last_failure_atstring (date-time)
namerequiredstring
okrequiredboolean
subscriptionstring
subscription_sincestring (date-time)
wherestring
CourierLastQuote

CourierLastQuote is one enabled connector's last test quote (version 6, additive), for the courier card's line "Last quote, 4 minutes ago": its name and environment; when the owner last tried it in that environment (null for never); whether the courier was asked; and its cheapest rate (null when it gave none, or was not asked). The engine keeps it over a restart; a buyer's quote never changes it.

environmentrequiredstring
last_quote_askedrequiredboolean
last_quote_atrequiredstring (date-time)
last_quote_cheapestrequiredMoney
namerequiredstring
CourierMarkup

CourierMarkup is the store's markup on a courier's price: a percentage in basis points (1000 is 10 %), then a fixed amount, then a rounding up to a step, both in the store currency's minor units; zero for none.

fixed_minorrequiredinteger
percent_bprequiredinteger
round_minorrequiredinteger
CourierParcel

CourierParcel is a default parcel's size in mm and weight in g; all zero for none.

height_mmrequiredinteger
length_mmrequiredinteger
weight_grequiredinteger
width_mmrequiredinteger
CourierProblem

CourierProblem is a fault of a courier set at its field, such as connectors[0].environment or connectors[0].name, and why, in words. From version 6.

fieldrequiredstring
reasonrequiredstring
CourierSettings

CourierSettings are the store's couriers as they rule: whether the owner saved them, or they are store.yaml's courier section (revision 0); the revision each save sends back; who saved them and when (null while not saved); the connectors enabled; and whether one of them books (can_book,: /admin offers a courier booking only then; version 6, additive).

can_bookrequiredboolean
closed_datesrequiredarray of string
connectorsrequiredarray of EnabledConnector
couriers_offstring
healthrequiredarray of CourierHealth
last_quotesrequiredarray of CourierLastQuote
live_mismatchrequiredarray of CourierProblem
quote_valid_daysrequiredinteger
quotes_skippedstring
quotes_skipped_wordsstring
revisionrequiredinteger
savedrequiredboolean
saved_atrequiredstring (date-time)
saved_byrequiredstring
set_asidestring
ship_by_handrequiredboolean
working_daysrequiredarray of string
CourierSettingsRequest

CourierSettingsRequest replaces the store's couriers whole, sent with the revision the owner read (a save sent with another is refused, 409). A set with a fault is refused (422) naming each.

closed_datesrequiredarray of string
connectorsrequiredarray of EnabledConnector
quote_valid_daysrequiredinteger
revisionrequiredinteger
ship_by_handrequiredboolean
working_daysrequiredarray of string
DeskCourier

DeskCourier is one card's answer to a desk quote: as a test quote says it (Asked, NotAsked, Words, TookMS, WaitMS), with its rates. A quote asked again says a card the store's set no longer enables NotInSet. A courier asked that gave no rate says why by NoPrice (31e): NoPriceNone, NoPriceFailed or NoPriceSlow; "" when it gave a rate or was not asked.

askedrequiredboolean
connectorrequiredstring
display_namerequiredstring
environmentrequiredstring
no_pricestring
not_askedrequiredstring
ratesrequiredarray of DeskRate
took_msrequiredinteger
wait_msrequiredinteger
wordsrequiredstring
DeskQuote

DeskQuote is a desk quote's answer: where it quotes from (the store's address), and each card of the store's set in its order.

couriersrequiredarray of DeskCourier
fromrequiredAddress
DeskQuoteRequest

DeskQuoteRequest is a desk quote (the quote desk; from version 6, additive): the address it goes to, 1 to MaxDeskParcels parcels as the owner packed them (each with its weight), and the goods' worth in the store's currency's minor units.

cityrequiredstring
countryrequiredstring
couriersrequiredarray of string
line1requiredstring
line2requiredstring
parcelsrequiredarray of CourierParcel
postal_coderequiredstring
provincerequiredstring
suburbrequiredstring
worth_minorrequiredinteger
DeskRate

DeskRate is one rate of a desk quote, as a kept quote keeps it: the price the store charges (the card's markup), the courier's own price (null for a card priced at the checkout, which gives it not apart), the delivery dates (YYYY-MM-DD; "" when the courier gives none) and the point a pickup rate goes to. Connector is the connector that gave it, which, with ServiceCode and the point's id, is the rate's stable key (orders.place's quote; additive).

carrierrequiredstring
connectorrequiredstring
courier_pricerequiredMoney
delivery_fromrequiredstring
delivery_torequiredstring
kindrequiredstring
pointrequiredTestQuotePoint
pricerequiredMoney
servicerequiredstring
service_coderequiredstring
EnabledConnector

EnabledConnector is one connector the store has enabled: its name; sandbox or production; the names of its secrets under secrets: in store.yaml (never a secret); its rate source, checkout or courier; the service codes offered (none for every one); the markup on its prices, whatever the source; the delivery kinds offered at the checkout (door, pickup_point, locker, in_store; none for booking alone); the checkout quote's time in ms; the default parcel; the booking defaults; and a demo connector's carrier name ("" for its own; version 6, additive).

book_on_paymentrequiredboolean
carrier_namerequiredstring
collectionrequiredCourierCollection
default_parcelrequiredCourierParcel
environmentrequiredstring
key_presentrequiredboolean
key_secretrequiredstring
kindsrequiredarray of string
label_sizerequiredstring
markuprequiredCourierMarkup
namerequiredstring
quote_timeout_msrequiredinteger
rate_sourcerequiredstring
service_namesmap of string
servicesrequiredarray of string
uninsuredrequiredboolean
webhook_presentrequiredboolean
webhook_secretrequiredstring
KeepQuoteRequest

KeepQuoteRequest is a quote to keep (the quote desk; from version 6, additive): the customer (a name, an e-mail, or both), the address, the parcels as the owner packed them, the goods' worth and a note.

cityrequiredstring
countryrequiredstring
couriersrequiredarray of string
customer_emailrequiredstring
customer_namerequiredstring
keeparray of QuoteRateKey
line1requiredstring
line2requiredstring
noterequiredstring
parcelsrequiredarray of CourierParcel
postal_coderequiredstring
provincerequiredstring
suburbrequiredstring
valid_daysinteger
worth_minorrequiredinteger
KeptQuote

KeptQuote is a kept quote of the quote desk: its reference (QT-0001), its status (kept, sent, ordered), the customer, the address, the parcels, the goods' worth, its rates as the desk gave them (the store's price is its promise until valid_until), the note, whether it has expired now, who made it and when, the order made from it (0 for none) and each sending. Couriers is the desk's answer when it was just made or asked again (why a courier gave no rate); empty on a read.

addressrequiredAddress
couriersrequiredarray of DeskCourier
created_atrequiredstring (date-time)
created_byrequiredstring
customerrequiredQuoteCustomer
expiredrequiredboolean
idrequiredinteger
noterequiredstring
order_numberrequiredinteger
parcelsrequiredarray of CourierParcel
ratesrequiredarray of DeskRate
referencerequiredstring
sendsrequiredarray of QuoteSend
statusrequiredstring
valid_untilrequiredstring (date-time)
worthrequiredMoney
KeptQuotes

KeptQuotes is a page of kept quotes, newest first, and the id to go on after (0 at the end).

nextrequiredinteger
quotesrequiredarray of KeptQuote
Money

Money is an amount: in minor units of its ISO 4217 currency, and as the store displays it.

currencyrequiredstring
displayrequiredstring
minorrequiredinteger
QuoteCustomer

QuoteCustomer is who a kept quote is for.

emailrequiredstring
namerequiredstring
QuoteRateKey

QuoteRateKey names a rate of a desk quote: its connector and service code, and the point's id for a rate to one ("" for every point).

connectorrequiredstring
point_idstring
service_coderequiredstring
QuoteSend

QuoteSend is one sending of a kept quote: when, to what address, by whom.

atrequiredstring (date-time)
byrequiredstring
torequiredstring
ShippingArea

ShippingArea is a place a zone holds: a country (ISO 3166-1 alpha-2), alone, or with one province, or with one range of postal codes, from and to both held.

countryrequiredstring
postal_fromstring
postal_tostring
provincestring
ShippingBand

ShippingBand is a band of weight: parcels of at most UpToG grams in all, above the band before it, cost Price.

pricerequiredMoney
up_to_grequiredinteger
ShippingBandRequest

ShippingBandRequest is a band of weight as the owner enters it.

pricerequiredstring
up_to_grequiredinteger
ShippingBox

ShippingBox is one of the store's own boxes: its name; its inner size in mm; its own weight in g; the most it carries in g, its own weight not counted; its outer size in mm, the size the courier is told, absent for none (the inner size is told); and who saved it last and when (absent while store.yaml's rules).

inner_height_mmrequiredinteger
inner_length_mmrequiredinteger
inner_width_mmrequiredinteger
max_weight_grequiredinteger
namerequiredstring
outer_height_mminteger
outer_length_mminteger
outer_width_mminteger
saved_atstring (date-time)
saved_bystring
weight_grequiredinteger
ShippingBoxRequest

ShippingBoxRequest is one box as the owner enters it: as ShippingBox shows it, without who saved it; each outer side 0, or left out, for none.

inner_height_mmrequiredinteger
inner_length_mmrequiredinteger
inner_width_mmrequiredinteger
max_weight_grequiredinteger
namerequiredstring
outer_height_mminteger
outer_length_mminteger
outer_width_mminteger
weight_grequiredinteger
ShippingBoxesRequest

ShippingBoxesRequest replaces the store's boxes whole: the table's revision as the owner read it, and the boxes in order; none takes them all away. At most 20 boxes; each name given and at most 64 characters, not given twice; each number whole and above 0; the outer size all three sides or none. A fault is refused (422) naming its field path, such as boxes[2].inner_width_mm.

boxesrequiredarray of ShippingBoxRequest
revisionrequiredinteger
ShippingChange

ShippingChange is the record of a save of the table: its revision, whether it added, changed or removed the zone, the zone's id and name, and who saved it and when.

atrequiredstring (date-time)
byrequiredstring
changerequiredstring
idrequiredinteger
revisionrequiredinteger
zonerequiredstring
ShippingOptionsRequest

ShippingOptionsRequest sets the most door options the checkout shows (courier curation B; version 6, additive): the table's revision as the owner read it, and the most, a whole number 0 or more (0, or left out, for no cap). Below 0 is refused (422) naming door_options_max.

door_options_maxrequiredinteger
revisionrequiredinteger
ShippingRate

ShippingRate is a zone's one rate: a flat price, or bands of weight, in increasing weight; and the worth of the goods from which it is free, absent for none. Each price is VAT-inclusive.

bandsarray of ShippingBand
flatMoney
free_atMoney
ShippingRateRequest

ShippingRateRequest is a zone's rate as the owner enters it, each price text with exactly two decimals: a flat price, or bands of weight, which replace it; and the worth from which it is free, "" for none.

bandsarray of ShippingBandRequest
flatstring
free_atstring
ShippingRemoveRequest

ShippingRemoveRequest removes the zone its path names: the table's revision as the owner read it.

revisionrequiredinteger
ShippingWarning

ShippingWarning warns of an area: its zone, the region as written, and the warning in the store's words.

messagerequiredstring
regionrequiredstring
zonerequiredstring
ShippingZone

ShippingZone is one zone: its id, its name, the areas it holds (none for everywhere else), its rate, and who saved it and when (none while store.yaml's rules).

areasrequiredarray of ShippingArea
idrequiredinteger
namerequiredstring
raterequiredShippingRate
saved_atstring (date-time)
saved_bystring
ShippingZoneRequest

ShippingZoneRequest adds a zone, or replaces the zone its path names, whole: the table's revision as the owner read it; the zone's name; its areas, none for everywhere else; and its rate.

areasrequiredarray of ShippingArea
namerequiredstring
raterequiredShippingRateRequest
revisionrequiredinteger
ShippingZones

ShippingZones are the table of shipping zones as it rules: whether the owner saved it, or it is store.yaml's as the first save copies it; its revision, which each write sends back (0 while nothing is saved); and its zones, in the order of their ids.

boxesrequiredarray of ShippingBox
changesrequiredarray of ShippingChange
door_options_maxrequiredinteger
door_options_saved_atstring (date-time)
door_options_saved_bystring
revisionrequiredinteger
savedrequiredboolean
warningsrequiredarray of ShippingWarning
zonesrequiredarray of ShippingZone
TestQuote

TestQuote is a connector's answer to a test quote, as the checkout would offer its rates: who was asked and in which environment; from the store's address to the address asked; the parcel; the rates; why there are none, in the engine's words ("" when the courier answered); how long the courier took, and how long the checkout waits for it (the card's quote_timeout_ms). It never books. Version 6.

askedrequiredboolean
connectorrequiredstring
environmentrequiredstring
fromrequiredAddress
not_askedrequiredstring
parcelrequiredCourierParcel
ratesrequiredarray of TestQuoteRate
torequiredAddress
took_msrequiredinteger
wait_msrequiredinteger
wordsrequiredstring
TestQuotePoint

TestQuotePoint is a pickup rate's point: its id, its name, its address on one line, and how far it is from the address asked in metres (null when the courier gives no distance).

addressrequiredstring
distance_mrequiredinteger
idrequiredstring
namerequiredstring
TestQuoteRate

TestQuoteRate is one rate of a test quote: its service, service code, carrier, kind (door, pickup_point or locker) and price, and the point a pickup rate goes to (null for a door rate).

carrierrequiredstring
kindrequiredstring
pointrequiredTestQuotePoint
pricerequiredMoney
servicerequiredstring
service_coderequiredstring

Made from engine/internal/openapi/openapi.json at commit 6c4cbd921. The contract-only operations come from the engine’s stub file, engine/internal/ops.