Orders. 40 operations.
40 of them work. Page 1 of 2. Each needs a bearer token with its scope. All operations.
Operations
POST/api/v1/orders/{number}/notesorders.add-noteorders.write
GET/api/v1/orders/attentionorders.attentionorders.read
GET/api/v1/orders/attention/itemsorders.attention-itemsorders.read
POST/api/v1/orders/{number}/book-courierorders.book-courierorders.write
POST/api/v1/orders/{number}/cancelorders.cancelorders.write
POST/api/v1/orders/{number}/shipments/{id}/cancelorders.cancel-courierorders.write
GET/api/v1/orders/cancel-reasonsorders.cancel-reasonsorders.read
POST/api/v1/orders/checkorders.checkquotes.write
POST/api/v1/orders/{number}/collect-cashorders.collect-cashorders.write
POST/api/v1/orders/{number}/shipments/{id}/referenceorders.confirm-courierorders.write
Parameters
numberpath | string |
idpath | string |
numberpath | string |
idpath | string |
Idempotency-Keyheader | stringSee common parameters |
Request body
Answer
Errors: 401, 403, 404, 405, 409, 413, 422, 429
curl -X POST -H "Authorization: Bearer $TOKEN" https://yourshop.example/api/v1/orders/{number}/shipments/{id}/reference
POST/api/v1/orders/{number}/shipmentorders.correct-shipmentorders.write
GET/api/v1/orders/countsorders.countsorders.read
GET/api/v1/orders/{number}/shipments/{id}/labelorders.courier-labelorders.read
POST/api/v1/orders/{number}/shipments/{id}/not-bookedorders.courier-not-bookedorders.write
Parameters
numberpath | string |
idpath | string |
numberpath | string |
idpath | string |
Idempotency-Keyheader | stringSee common parameters |
Request body
Answer
Errors: 401, 403, 404, 405, 409, 413, 422, 429
curl -X POST -H "Authorization: Bearer $TOKEN" https://yourshop.example/api/v1/orders/{number}/shipments/{id}/not-booked
GET/api/v1/orders/{number}/courier-ratesorders.courier-ratesorders.read
POST/api/v1/orders/{number}/deliverorders.deliverorders.write
POST/api/v1/orders/{number}/attention/dismissorders.dismiss-attentionorders.write
GET/api/v1/orders/exportorders.exportorders.read
Parameters
qquery | stringThe words to search the orders for: a number, a name, an email. |
statusquery | stringOnly the orders in this status. |
placedquery | stringtoday: only the orders placed today, in the store time zone. |
placed_fromquery | stringOnly the orders placed from this date (in the store time zone). |
placed_toquery | stringOnly the orders placed up to this date (in the store time zone). |
paymentquery | stringOnly the orders in this payment state. |
methodquery | stringOnly the orders paid by this payment method id. |
deliveryquery | stringOnly the orders of this delivery kind. |
to_packquery | booleantrue: only the orders to pack; false: only the others. |
ready_for_collectionquery | booleantrue: only the orders ready for the buyer to collect at the store's place. |
skuquery | stringOnly the orders with a product line of this SKU. |
made_to_orderquery | booleantrue: only the orders with a made-to-order line. |
sourcequery | stringOnly the orders made at the shop (shop), entered by the owner (admin) or sold at the till (pos). |
placequery | stringOnly the sales at the till made at the stock place of this key. |
sortquery | stringThe order of the answer; newest first when left out. |
Answer
no body
Errors: 401, 403, 405, 422, 429
curl -X GET -H "Authorization: Bearer $TOKEN" https://yourshop.example/api/v1/orders/export
GET/api/v1/orders/{number}orders.getorders.read
POST/api/v1/orders/{number}/downloads/{sku}orders.grant-more-downloadsorders.write
Schemas 57
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 |
AttentionChange
AttentionChange is what a dismissal did: whether it changed the list, and the order's item as the list then holds it, absent once the order left it.
changedrequired | boolean |
item | AttentionItem |
AttentionDismissal
AttentionDismissal is the mail reason an owner dismisses from an order's place on the attention list: one of the mail reasons of AttentionItem.
reasonrequired | string |
AttentionItem
AttentionItem is an order on the attention list and why it is there, one or more codes of AttentionReasons.
modules | array of string |
orderrequired | Order |
reasonsrequired | array of string |
BookCourierRequest
BookCourierRequest books an order with one connector's service, by its code. AnotherParcel is the owner's act of booking an order that holds a booked shipment again: a second parcel or a replacement (refused, 409, without it). An order whose booking is still out, or whose outcome is not known, is refused (409) whatever it says: the owner resolves an unknown one first.
another_parcelrequired | boolean |
collection_afterrequired | string |
collection_beforerequired | string |
collection_daterequired | string |
connectorrequired | string |
service_coderequired | string |
Buyer
CancelReason
CancelReason is a reason a cancel is picked from: the text the buyer is shown, and, for one of the engine's five, its code; "" for a reason the owner wrote.
code | string |
textrequired | string |
CancelRequest
CancelRequest is why an order is cancelled (from version 6), all optional: a reason of 1 to 200 characters on one line, which the buyer is shown; its code, one of customer_request, out_of_stock, duplicate, payment_problem or other, only with a reason; and the owner's note of 1 to 500 characters, which the buyer never sees.
code | string |
note | string |
reason | string |
CashCollected
CashCollected is the cash of an order paid on delivery as it was collected.
actorrequired | string |
amountrequired | Money |
atrequired | string (date-time) |
how | string |
reference | string |
CollectCashRequest
CollectCashRequest is the owner's record that the cash of an order paid on delivery was collected: Amount is a price with two decimals, such as 439.00, which must be the cash to collect; left out, it is the cash to collect.
amount | string |
CollectPlace
CollectPlace is a place of the store the buyer collects an order at, as the order keeps it: the place's key and name, its address in one line (the street, the suburb, the city and the postal code, as far as each is known) and its opening hours as the owner wrote them (CR-4).
addressrequired | string |
hoursrequired | string |
keyrequired | string |
namerequired | string |
CollectionAsked
CollectionAsked is the window a booking asked the courier to collect in (collection,; version 6, additive): its day and hours in the store's time zone, an IANA name.
afterrequired | string |
beforerequired | string |
dayrequired | string |
time_zonerequired | string |
CourierEvent
CourierEvent is one tracking event a courier gave of a shipment: the state it mapped to, when, and the courier's words of it: its text and its location, "" when it gave none (an erased order's are blank).
atrequired | string (date-time) |
locationrequired | string |
staterequired | string |
textrequired | string |
CourierLabel
CourierLabel is a shipment's label as the engine kept it: the shipment's id, the document's media type (application/pdf) and its bytes, base64 in JSON.
content_typerequired | string |
pdfrequired | string |
shipmentrequired | integer |
CourierNotBooked
CourierNotBooked records that a shipment whose booking's outcome is not known was not made, in the owner's words (the courier's dashboard shows none): it is cancelled, and the order may be booked again.
wordsrequired | string |
CourierOption
CourierOption is one service: its connector (by name, and the name a person reads), the service's name and code, the carrier, the courier's price, VAT-inclusive, and whether it is the default (the service the order's shipping line named, else the cheapest). DefaultReason (K8, additive) says why the default is: buyer (the buyer's service), store_level (the buyer chose a store rate: the cheapest service of its connector at its level), store_cheapest (a store rate with no service at its level: the cheapest) or cheapest (no courier quoted the order); absent on the others.
carrierrequired | string |
connectorrequired | string |
defaultrequired | boolean |
default_reason | string |
display_namerequired | string |
pricerequired | Money |
servicerequired | string |
service_coderequired | string |
CourierRates
CourierRates are the services the owner may book an order with: each courier rate, for the order's parcels to its address, of every courier the store set up to book.
optionsrequired | array of CourierOption |
CourierReference
CourierReference is the courier's own reference of a shipment whose booking's outcome is not known, as the owner read it in the courier's dashboard: accepted only when the courier's shipments of this account hold it and no other shipment of the store has it.
referencerequired | string |
CourierShipment
CourierShipment is one booking of a courier for an order: its id; the connector and environment that booked it; the service; the courier's reference and the carrier's waybill ("" until given); its state (booking, booked, collected, in_transit, out_for_delivery, ready_for_collection, delivered, problem, returned, cancelled or unknown; the two finer states of a parcel on its way from ) and the courier's own word for a state it does not map; what the buyer paid and what the courier charges (zero until it says); the estimated dates (YYYY-MM-DD, "" for none); the courier's tracking page; whether its label is kept; when it was made and booked (null until the courier answered); who booked it; and who resolved its unknown booking and when (null for none). From the step that added them: whether the courier did not give its label within a day; where its cancel at the courier stands ("" for none, requested or failed), the courier's or the engine's words when it failed, and who asked for it ("" for the order's cancel or refund). The state's text and the cancel's words are the engine's own, said in the catalogue's language, or the courier's text as it is, at most 300 runes: show both as text, never as markup.
booked_atrequired | string (date-time) |
booked_byrequired | string |
cancelrequired | string |
cancel_byrequired | string |
cancel_wordsrequired | string |
carrierrequired | string |
chargedrequired | Money |
collection_askedrequired | CollectionAsked |
collection_daterequired | string |
connectorrequired | string |
created_atrequired | string (date-time) |
delivery_daterequired | string |
environmentrequired | string |
eventsrequired | array of CourierEvent |
has_labelrequired | boolean |
idrequired | integer |
insuredrequired | Money |
label_overduerequired | boolean |
paidrequired | Money |
referencerequired | string |
resolved_atrequired | string (date-time) |
resolved_byrequired | string |
servicerequired | string |
service_coderequired | string |
staterequired | string |
state_textrequired | string |
tracking_urlrequired | string |
waybillrequired | string |
DeliveryFacts
DeliveryFacts are an order's delivery (from version 6): its kind, one of the Delivery kinds; its method in the engine's words (the zone's name, the flat rate, the courier's service and how it reaches the buyer, or no delivery); the shipping line's price; and how many units of products the order holds.
itemsrequired | integer |
kindrequired | string |
pricerequired | Money |
wordsrequired | string |
DownloadRecord
DownloadRecord is one download of a grant: when, and the SHA-256 of the file it served. From version 6.
atrequired | string (date-time) |
digestrequired | string |
DownloadsChanged
DownloadsChanged is the answer to a change of a grant (from version 6): the order, its line's Download as it now stands; whether the buyer was mailed; and, when notify was asked but no mail queued, why not, as OrderChange says it: NotMailed, theme or stream, and Note, the same in the catalogue's words.
mailedrequired | boolean |
not_mailed | string |
note | string |
orderrequired | Order |
Event
Event is one change of an order's status.
actorrequired | string |
atrequired | string (date-time) |
carrier | string |
code | string |
corrects | integer |
note | string |
reason | string |
statusrequired | string |
tracking | string |
GrantMoreRequest
GrantMoreRequest is the owner's change of an order line's download grant (from version 6): downloads added, 0 to 99, the most then at most 100; a new expiry, after now and at most 3650 days from now, null for the expiry in force; at least one of the two; why, one line of 1 to 200 characters; and whether it deliberately re-grants a grant revoked with the order's cancel or refund.
expires_atrequired | string (date-time) |
morerequired | integer |
notifyrequired | boolean |
reasonrequired | string |
regrantrequired | boolean |
Line
Line is one line of an order, as copied at confirm.
choicesrequired | array of LineChoice |
combo | LineCombo |
discountrequired | Money |
download | LineDownload |
kindrequired | string |
made_to_orderrequired | boolean |
no_delivery | boolean |
option_valuesrequired | array of string |
pickup_point | PickupPoint |
price_log | LinePriceLog |
production_daysrequired | integer |
quantityrequired | integer |
quote | Quote |
quoted_by | string |
skurequired | string |
titlerequired | string |
totalrequired | Money |
unit_pricerequired | Money |
LineChoice
LineChoice is a buyer's answer on a cart line or an order line: the label the field had at the confirm, and the value. An order never changes it, and a privacy erasure of the buyer replaces a text value with the catalogue's word "erased".
keyrequired | string |
labelrequired | string |
valuerequired | string |
LineCombo
LineCombo is the combo a part line came from: its SKU and its title as they were at confirm, how many combos the order holds, and Index, which combo line of the cart it was, from 0 (two lines of one combo at two cadences stay apart). First is true on the first part line of the combo. Total, Discount and VAT are the sums of the combo's part lines: the discount, the total after it and the VAT in it.
LineDownload
LineDownload is a digital line's download grant as the owner sees it: the most downloads it allows, the downloads used, its expiry, when it was revoked (null while it stands), and its downloads, newest first, at most 50, each with the digest of the file it served; no IP address and no user agent are kept. From version 6.
expires_atrequired | string (date-time) |
maxrequired | integer |
recordsrequired | array of DownloadRecord |
regranted_atrequired | string (date-time) |
revoked_atrequired | string (date-time) |
usedrequired | integer |
LinePriceLog
LinePriceLog is the price log of an order line the owner priced: Reason, By (who set the price, such as user:owner), At, and Catalogue, the catalogue's price of one unit it stands against (zero for a custom line, which has none).
atrequired | string (date-time) |
byrequired | string |
cataloguerequired | Money |
reasonrequired | string |
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 |
Order
Order is an order as the owner sees it.
actionsrequired | array of string |
amount_duerequired | Money |
buyerrequired | Buyer |
cashrequired | OrderCash |
collect | CollectPlace |
deliveryrequired | DeliveryFacts |
dispatch_byrequired | string |
eventsrequired | array of Event |
fee_keptrequired | boolean |
flagsrequired | array of string |
gatewayrequired | string |
gift_card_paidrequired | Money |
linesrequired | array of Line |
linked | OrderLink |
methodrequired | string |
notesrequired | array of OrderNote |
numberrequired | integer |
paymentrequired | PaymentFacts |
placed_atrequired | string (date-time) |
po_number | string |
pos | OrderPOS |
refundablerequired | Money |
refundsrequired | array of Refund |
shipmentsrequired | array of Shipment |
sourcerequired | string |
statusrequired | string |
tendersrequired | array of Tender |
terms | OrderTerms |
timelinerequired | array of TimelineEntry |
totalrequired | Money |
OrderCash
OrderCash is the cash of an order paid on delivery: what is to be collected, the order's frozen total, and, once it was, the cash collected (null before): when, how much and who said so (the owner, an integration, or the courier). The order's status is not changed by it. An order under account terms shows it too, as its payment on account: ToCollect is the invoice's total and Collected the payment once recorded, with how it was made and its reference (additive).
collectedrequired | CashCollected |
to_collectrequired | Money |
OrderChange
OrderChange is an order as an operation left it, and whether the operation changed it: an order already where the operation takes it is left as it is.
changedrequired | boolean |
not_mailed | string |
note | string |
orderrequired | Order |
OrderCounts
OrderCounts are how many orders are in each status, every status listed, 0 for none, and how many were placed today, the store's calendar day in its time zone.
by_statusrequired | map of integer |
placed_todayrequired | integer |
ready_for_collectionrequired | integer |
to_packrequired | integer |
OrderLink
OrderLink is the other order of a pair of linked orders: its number and its role in the pair, deposit or balance (the opposite of the role of the order that carries the link).
numberrequired | integer |
rolerequired | string |
OrderNote
OrderNote is one internal note of an order (from version 6): its text, who wrote it in words (owner, or an integration's name), and when. No buyer's page or mail shows it.
atrequired | string (date-time) |
byrequired | string |
textrequired | string |
OrderNoteRequest
OrderNoteRequest is an internal note the owner adds to an order (from version 6): its text, 1 to OrderNoteLimit characters once trimmed.
textrequired | string |
OrderPOS
OrderPOS is the sale at the till an order is: the key and the name of the stock location it was sold at, the device and its sale number, when it was sold by the device's clock (the order's placed_at is when the store received it).
devicerequired | string |
locationrequired | string |
location_namerequired | string |
made_before_stoprequired | boolean |
price_differsrequired | boolean |
sale_numberrequired | string |
seller | OrderSeller |
sold_atrequired | string (date-time) |
OrderSeller
OrderSeller is the team member who sold a sale at the till: the account's id, its name ("" for none) and its email.
emailrequired | string |
idrequired | integer |
namerequired | string |
OrderTerms
OrderTerms are the payment terms an order was entered under: the term's id in the store's settings, its kind (pay_now, eft or account), the days after the invoice that it falls due (0: on receipt) and the moment of the tax invoice (accepted or dispatched; "" for a kind that has none).
due_daysrequired | integer |
idrequired | string |
invoice_at | string |
kindrequired | string |
PaymentFacts
PaymentFacts are an order's payment (from version 6): its method's id and its gateway's name ("" for none); what it paid, its frozen total once paid, else nothing; when it was paid, null while it never was; the gateway's reference of its last captured payment, "" for none; and what was refunded of it, declined refunds aside. State is where its payment stands, one of the Payment states, "" for none of them (such as an order cancelled before it was paid), by the rule orders.search's payment filter narrows by.
PickupPoint
PickupPoint is a pickup point or a locker an order is delivered to, as the courier connector listed it at the confirm: the connector's id of it, its kind (pickup_point or locker), who runs it, its name, the courier's own words about it, its address, where it is (lat and lng, null when not known), its distance in metres from the buyer's address (null when not given), its hours, one line per day as given, and provider, the connector that listed it, which books it. From version 6.
addressrequired | PostalAddress |
carrierrequired | string |
descriptionrequired | string |
distance_mrequired | integer |
hoursrequired | array of string |
idrequired | string |
kindrequired | string |
latrequired | number |
lngrequired | number |
namerequired | string |
providerrequired | string |
PlaceBuyer
PlaceBuyer is who the order is for, as the owner types them (until the customer records are built): the name and the email are required; the delivery address when something ships; the billing address when it differs.
billing | PostalAddress |
business_name | string |
delivery | PostalAddress |
emailrequired | string |
namerequired | string |
phone | string |
vat_number | string |
PlaceCheck
PlaceCheck is what orders.check answers: the order as it would be (its number is 0), the VAT in its total, the number it would get (a hint: another order placed first takes it), and the warnings, in words, that placing it would give. Nothing was made.
PlaceLine
PlaceLine is a line of the order: a catalogue variant (SKU, Quantity) or a custom line (Title, Quantity, Price). Price is a price with two decimals, such as 300.00: for a custom line always, for a variant line only to depart from the catalogue's. DiscountPercent (such as 12.5) or DiscountAmount (a price) takes something off a variant line, not both; a price or a discount other than the catalogue's needs a Reason (at most 300 characters), kept in the line's price log with who set it and when. NoVAT makes a custom line free of VAT.
discount_amount | string |
discount_percent | string |
less_deposit | boolean |
no_vat | boolean |
price | string |
quantityrequired | integer |
reason | string |
sku | string |
title | string |
unit_price | integer |
PlaceOrderRequest
PlaceOrderRequest is the order the owner enters at once (orders.place): the buyer, the lines, the shipping, the payment term, the purchase order number and one of the three ways to pay. It is one transaction: it makes the order and what the term and the way make with it, or nothing. The same Idempotency-Key gives the same order.
apply_promotions | boolean |
buyerrequired | PlaceBuyer |
client | integer |
deposit_order | integer |
form_key | string |
linesrequired | array of PlaceLine |
method | string |
payment | PlacePayment |
po_number | string |
pos | PlacePOS |
prices_exclude_vat | boolean |
quote | PlaceQuote |
shipping | PlaceShipping |
termrequired | string |
term_override | string |
wayrequired | string |
PlacePOS
PlacePOS is a sale at the till (-): the key of an active stock location it was sold at; the device that sold it and its sale number there, each 1 to 64 visible characters; and when it was sold, by the device's clock (RFC 3339), at most 5 minutes ahead of the store's clock and at most pos.max_sale_age_days (30 when the store gives none) before it.
catalogue_at | string (date-time) |
devicerequired | string |
locationrequired | string |
sale_numberrequired | string |
seller | integer |
sold_atrequired | string (date-time) |
PlacePayment
PlacePayment is the payment of a "paid" order: How is one of PaymentHows, Reference one line of at most 100 characters, ReceivedOn a date such as 2026-10-19 in the store's zone, not in the future (today when left out).
howrequired | string |
received_on | string |
reference | string |
PlaceQuote
PlaceQuote is the kept quote an order is made from and the rate of it that is chosen, by its stable key: the connector and the courier's service code, as the quote desk and the booking use them.
connectorrequired | string |
idrequired | integer |
point_id | string |
service_coderequired | string |
PlaceShipping
PlaceShipping is the shipping the owner types: Kind is "price" (Price, a price with two decimals), "free", "collect" (the buyer collects it: no shipping line is booked) or "none"; Label names the shipping line of a price or free.
kindrequired | string |
label | string |
price | string |
PostalAddress
PostalAddress is an address in its fields, as the store's details take and give it. From contract version 6.
cityrequired | string |
countryrequired | string |
country_name | string |
line1required | string |
line2required | string |
postal_coderequired | string |
provincerequired | string |
suburbrequired | string |
text | string |
Quote
Quote is what a courier said of an order's shipping line, each part "" when it did not say: the service's name, the carrier, the courier's code of the service, how the parcel reaches the buyer (door, pickup_point or in_store), and the estimated delivery dates (YYYY-MM-DD).
carrierrequired | string |
delivery_fromrequired | string |
delivery_torequired | string |
display_name | string |
kindrequired | string |
servicerequired | string |
service_coderequired | string |
Refund
Refund is one refund of an order.
actorrequired | string |
amountrequired | Money |
atrequired | string (date-time) |
cancelrequired | boolean |
reasonrequired | string |
staterequired | string |
Shipment
Shipment is one shipment of an order as last corrected (from version 6): the id a correction names, the carrier and tracking number, when it was shipped, and whether the owner corrected it since.
atrequired | string (date-time) |
carrierrequired | string |
correctedrequired | boolean |
idrequired | integer |
trackingrequired | string |
ShipmentCorrection
ShipmentCorrection is a correction of a shipped order's shipment (from version 6): the shipment, by its id, which may be left out when the order has one; its carrier and tracking number, checked as a ship's; and whether the buyer is sent the corrected tracking, true when absent.
carrier | string |
notify | boolean |
shipment | integer |
tracking | string |
Tender
TimelineEntry
TimelineEntry is one thing that happened to an order (from version 6): when; its kind, one of the Timeline kinds; who did it, in words (owner, guest, payment, system, courier, or an integration's name, never its raw id); the engine's words for it; and, by kind, its status (a status entry's status, a refund's state, a payment's type such as captured or failed), its amount (a cash collected's, a payment's, a refund's), its reference (a payment's gateway reference, a shipment's tracking number), its SKU (a download grant's) and its template (a mail's type). Entries are oldest first; entries of the same time in the order of the kinds, then as they were recorded.
amount | Money |
atrequired | string (date-time) |
byrequired | string |
kindrequired | string |
reference | string |
sku | string |
status | string |
template | string |
wordsrequired | 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.