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
GET/api/v1/shipping/connectors/{connector}/servicesshipping.connector-servicesshipping.read
GET/api/v1/shipping/connectorsshipping.connectorsshipping.read
GET/api/v1/shipping/couriersshipping.couriersshipping.read
POST/api/v1/shipping/desk-quoteshipping.desk-quoteshipping.read
POST/api/v1/shipping/quotesshipping.keep-quoteshipping.write
GET/api/v1/shipping/quotes/{id}shipping.quoteshipping.read
POST/api/v1/shipping/quotes/{id}/againshipping.quote-againshipping.write
GET/api/v1/shipping/quotesshipping.quotesshipping.read
Parameters
afterquery | integerThe id to go on after: the page's next; none for the newest. |
limitquery | integerHow many quotes, at most 100; 50 when left out. |
activequery | booleantrue: only the quotes not ordered and not expired now. |
line1query | stringThe street address the quotes must fit; with the other address fields. |
line2query | stringThe unit, complex or building the quotes must fit. |
suburbquery | stringThe suburb the quotes must fit. |
cityquery | stringThe city or town the quotes must fit. |
postal_codequery | stringThe postal code the quotes must fit. |
provincequery | stringThe province the quotes must fit. |
countryquery | stringThe country's ISO 3166-1 alpha-2 code the quotes must fit. |
Answer
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
POST/api/v1/shipping/couriersshipping.save-couriersshipping.write
POST/api/v1/shipping/boxesshipping.set-boxesshipping.write
POST/api/v1/shipping/optionsshipping.set-optionsshipping.write
POST/api/v1/shipping/zones/{id}shipping.set-zoneshipping.write
GET/api/v1/shipping/connectors/{connector}/test-quoteshipping.test-quoteshipping.read
Parameters
connectorpath | string |
connectorpath | string |
postal_codequery | stringThe postal code the quote is asked to; with every address field left out, the sample address (12 Long Street, Cape Town, 8001). |
cityquery | stringThe city or town. |
suburbquery | stringThe suburb. |
provincequery | stringThe province. |
line1query | stringThe street address. |
countryquery | stringThe country's ISO 3166-1 alpha-2 code; ZA when left out. |
weight_gquery | integerThe parcel's weight in grams, 1 to 100000; the card's default parcel's when left out. |
Answer
Errors: 401, 403, 404, 405, 422, 429
curl -X GET -H "Authorization: Bearer $TOKEN" https://yourshop.example/api/v1/shipping/connectors/{connector}/test-quote
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.
cityrequired | string |
countryrequired | string |
country_namerequired | string |
linesrequired | array of string |
postal_coderequired | string |
provincerequired | string |
suburbrequired | string |
textrequired | string |
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.
answeredrequired | boolean |
answered_capabilities | array of string |
capabilitiesrequired | array of string |
currencyrequired | string |
declared_capabilities | array of string |
demorequired | boolean |
display_namerequired | string |
insures_alwaysrequired | boolean |
namerequired | string |
outside_capabilities | array 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.
carrierrequired | string |
chosenrequired | boolean |
coderequired | string |
in_samplerequired | boolean |
kind | string |
namerequired | string |
sample_price | Money |
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).
connectorrequired | string |
display_namerequired | string |
listedrequired | boolean |
more | string |
not_listed | string |
reason | string |
servicesrequired | array of ConnectorService |
took_msrequired | integer |
words | string |
Connectors
Connectors are the courier connectors the engine has, by name.
connectorsrequired | array 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.
afterrequired | string |
beforerequired | string |
cut_offrequired | string |
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).
checkedrequired | boolean |
checked_atrequired | string (date-time) |
display_namerequired | string |
environmentrequired | string |
failure | string |
last_failure | string |
last_failure_at | string (date-time) |
namerequired | string |
okrequired | boolean |
subscription | string |
subscription_since | string (date-time) |
where | string |
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.
environmentrequired | string |
last_quote_askedrequired | boolean |
last_quote_atrequired | string (date-time) |
last_quote_cheapestrequired | Money |
namerequired | string |
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_minorrequired | integer |
percent_bprequired | integer |
round_minorrequired | integer |
CourierParcel
CourierParcel is a default parcel's size in mm and weight in g; all zero for none.
height_mmrequired | integer |
length_mmrequired | integer |
weight_grequired | integer |
width_mmrequired | integer |
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.
fieldrequired | string |
reasonrequired | string |
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_bookrequired | boolean |
closed_datesrequired | array of string |
connectorsrequired | array of EnabledConnector |
couriers_off | string |
healthrequired | array of CourierHealth |
last_quotesrequired | array of CourierLastQuote |
live_mismatchrequired | array of CourierProblem |
quote_valid_daysrequired | integer |
quotes_skipped | string |
quotes_skipped_words | string |
revisionrequired | integer |
savedrequired | boolean |
saved_atrequired | string (date-time) |
saved_byrequired | string |
set_aside | string |
ship_by_handrequired | boolean |
working_daysrequired | array 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_datesrequired | array of string |
connectorsrequired | array of EnabledConnector |
quote_valid_daysrequired | integer |
revisionrequired | integer |
ship_by_handrequired | boolean |
working_daysrequired | array 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.
askedrequired | boolean |
connectorrequired | string |
display_namerequired | string |
environmentrequired | string |
no_price | string |
not_askedrequired | string |
ratesrequired | array of DeskRate |
took_msrequired | integer |
wait_msrequired | integer |
wordsrequired | string |
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.
couriersrequired | array of DeskCourier |
fromrequired | Address |
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.
cityrequired | string |
countryrequired | string |
couriersrequired | array of string |
line1required | string |
line2required | string |
parcelsrequired | array of CourierParcel |
postal_coderequired | string |
provincerequired | string |
suburbrequired | string |
worth_minorrequired | integer |
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).
carrierrequired | string |
connectorrequired | string |
courier_pricerequired | Money |
delivery_fromrequired | string |
delivery_torequired | string |
kindrequired | string |
pointrequired | TestQuotePoint |
pricerequired | Money |
servicerequired | string |
service_coderequired | string |
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_paymentrequired | boolean |
carrier_namerequired | string |
collectionrequired | CourierCollection |
default_parcelrequired | CourierParcel |
environmentrequired | string |
key_presentrequired | boolean |
key_secretrequired | string |
kindsrequired | array of string |
label_sizerequired | string |
markuprequired | CourierMarkup |
namerequired | string |
quote_timeout_msrequired | integer |
rate_sourcerequired | string |
service_names | map of string |
servicesrequired | array of string |
uninsuredrequired | boolean |
webhook_presentrequired | boolean |
webhook_secretrequired | string |
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.
cityrequired | string |
countryrequired | string |
couriersrequired | array of string |
customer_emailrequired | string |
customer_namerequired | string |
keep | array of QuoteRateKey |
line1required | string |
line2required | string |
noterequired | string |
parcelsrequired | array of CourierParcel |
postal_coderequired | string |
provincerequired | string |
suburbrequired | string |
valid_days | integer |
worth_minorrequired | integer |
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.
addressrequired | Address |
couriersrequired | array of DeskCourier |
created_atrequired | string (date-time) |
created_byrequired | string |
customerrequired | QuoteCustomer |
expiredrequired | boolean |
idrequired | integer |
noterequired | string |
order_numberrequired | integer |
parcelsrequired | array of CourierParcel |
ratesrequired | array of DeskRate |
referencerequired | string |
sendsrequired | array of QuoteSend |
statusrequired | string |
valid_untilrequired | string (date-time) |
worthrequired | Money |
KeptQuotes
KeptQuotes is a page of kept quotes, newest first, and the id to go on after (0 at the end).
nextrequired | integer |
quotesrequired | array of KeptQuote |
Money
Money is an amount: in minor units of its ISO 4217 currency, and as the store displays it.
currencyrequired | string |
displayrequired | string |
minorrequired | integer |
QuoteCustomer
QuoteCustomer is who a kept quote is for.
emailrequired | string |
namerequired | string |
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).
connectorrequired | string |
point_id | string |
service_coderequired | string |
QuoteSend
QuoteSend is one sending of a kept quote: when, to what address, by whom.
atrequired | string (date-time) |
byrequired | string |
torequired | string |
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.
countryrequired | string |
postal_from | string |
postal_to | string |
province | string |
ShippingBand
ShippingBand is a band of weight: parcels of at most UpToG grams in all, above the band before it, cost Price.
pricerequired | Money |
up_to_grequired | integer |
ShippingBandRequest
ShippingBandRequest is a band of weight as the owner enters it.
pricerequired | string |
up_to_grequired | integer |
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_mmrequired | integer |
inner_length_mmrequired | integer |
inner_width_mmrequired | integer |
max_weight_grequired | integer |
namerequired | string |
outer_height_mm | integer |
outer_length_mm | integer |
outer_width_mm | integer |
saved_at | string (date-time) |
saved_by | string |
weight_grequired | integer |
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_mmrequired | integer |
inner_length_mmrequired | integer |
inner_width_mmrequired | integer |
max_weight_grequired | integer |
namerequired | string |
outer_height_mm | integer |
outer_length_mm | integer |
outer_width_mm | integer |
weight_grequired | integer |
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.
boxesrequired | array of ShippingBoxRequest |
revisionrequired | integer |
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.
atrequired | string (date-time) |
byrequired | string |
changerequired | string |
idrequired | integer |
revisionrequired | integer |
zonerequired | string |
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_maxrequired | integer |
revisionrequired | integer |
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.
bands | array of ShippingBand |
flat | Money |
free_at | Money |
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.
bands | array of ShippingBandRequest |
flat | string |
free_at | string |
ShippingRemoveRequest
ShippingRemoveRequest removes the zone its path names: the table's revision as the owner read it.
revisionrequired | integer |
ShippingWarning
ShippingWarning warns of an area: its zone, the region as written, and the warning in the store's words.
messagerequired | string |
regionrequired | string |
zonerequired | string |
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).
areasrequired | array of ShippingArea |
idrequired | integer |
namerequired | string |
raterequired | ShippingRate |
saved_at | string (date-time) |
saved_by | string |
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.
areasrequired | array of ShippingArea |
namerequired | string |
raterequired | ShippingRateRequest |
revisionrequired | integer |
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.
boxesrequired | array of ShippingBox |
changesrequired | array of ShippingChange |
door_options_maxrequired | integer |
door_options_saved_at | string (date-time) |
door_options_saved_by | string |
revisionrequired | integer |
savedrequired | boolean |
warningsrequired | array of ShippingWarning |
zonesrequired | array 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.
askedrequired | boolean |
connectorrequired | string |
environmentrequired | string |
fromrequired | Address |
not_askedrequired | string |
parcelrequired | CourierParcel |
ratesrequired | array of TestQuoteRate |
torequired | Address |
took_msrequired | integer |
wait_msrequired | integer |
wordsrequired | string |
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).
addressrequired | string |
distance_mrequired | integer |
idrequired | string |
namerequired | string |
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).
carrierrequired | string |
kindrequired | string |
pointrequired | TestQuotePoint |
pricerequired | Money |
servicerequired | string |
service_coderequired | string |
Made from engine/internal/openapi/openapi.json at commit 6c4cbd921. The contract-only operations come from the engine’s stub file, engine/internal/ops.