Orders
Orders of every channel: items, totals, status and payment. The feed returns changes in commit order; status changes follow the rules of the store.
Orders
Objects
Order
idintegerrequiredID of the record, unique among records of its kind in the store.
numberstring or nullrequiredNumber of the order shown to the customer and the staff; null while the order has none yet.
channelstringrequiredWhere the order came from: web — the storefront; pos — the register; marketplace — a marketplace such as Mercado Libre; external — an accounting system of the store; manual — a draft order of the staff or an app; subscription — a day of a meal subscription.
- Values:
webposmarketplaceexternalmanualsubscription
app_idinteger or nullrequiredThe app that placed the order from its draft order (/v1/draft-orders), its id from /v1/me; null for orders of the storefront, the register or the staff.
location_idintegerrequiredLocation that serves the order: the pickup point or the location the stock is taken from.
legal_entity_idinteger or nullrequiredLegal entity the sale is made under (/v1/legal-entities); null — the sale is not split between legal entities, and its legal entity is the store default.
statusstringrequiredStatus of the order: a code from the status list of the store (/v1/order-statuses). A store can add its own statuses; status_group gives the lasting meaning.
status_groupstringrequiredLasting meaning of the status: pos_open — an open bill at the register; placed; pending_payment — waiting for payment; paid; confirmed — accepted by the store; preparing; ready; ready_for_pickup; out_for_delivery; delivery_failed; delivered; completed; cancelled; refunded.
- Values:
pos_openplacedpending_paymentpaidconfirmedpreparingreadyready_for_pickupout_for_deliverydelivery_faileddeliveredcompletedcancelledrefunded
payment_statusstringrequiredPayment of the order: unpaid; partial — paid in part; paid; partially_refunded; refunded.
- Values:
unpaidpartialpaidpartially_refundedrefunded
sale_typestringrequiredretail — a sale to a customer; staff — a sale to an employee; wholesale — a wholesale sale.
- Values:
retailstaffwholesale
currencystringrequiredCurrency of the amounts, an ISO 4217 code: the currency of the store.
items_totalintegerrequiredSum of the items before the order discount.
discountintegerrequiredDiscount on the order's goods: the sum of applied_discounts[].amount and of items[].discount.
applied_discountsarray of objectrequiredWhat the discount on goods is made of — the log of applied discounts. Rows are rewritten when the order is recalculated: an id lives until then.
Fields · 8
idintegerrequiredLog row; items[].discount_allocations[].applied_discount_id points to it.
sourcestringrequiredHow the discount got into the order: automatic — a store rule; pick — a rule the cashier selected; promocode — the buyer's promo code; manual — a cashier's manual discount; offline_capture — the gap between an offline register sale and the server's calculation, not a seller's decision; loyalty_program — a loyalty program; external_pos — the external POS that made the sale.
- Values:
promocodeautomaticpickmanualoffline_captureloyalty_programexternal_pos
kindstring or nullrequiredWhat the discount is for: promo — a promotion; employee — for staff; expiry — markdown for the expiry date; payment_method — for the payment method; markdown — markdown for the condition of the goods; goodwill — a gesture to the buyer; comp — on the house; other — something else. null — a discount of the external POS, an offline gap or a discount from before this axis existed.
- Values:
promoemployeeexpirypayment_methodmarkdowngoodwillcompothernull
nameobject or nullrequiredName of the rule or loyalty program at the time of sale; null for a promo code, a manual discount, an offline gap and the external POS.
codestring or nullrequiredThe promo code the buyer entered; null — not a promo code discount.
reasonstring or nullrequiredThe cashier's reason for a manual discount; null for the rest.
order_item_idinteger or nullrequiredThe item marked down on its own; null — a discount on the order, its shares per item are in items[].discount_allocations.
amountintegerrequiredDiscount amount.
delivery_costintegerrequiredDelivery to pay, after the delivery discount.
delivery_discountintegerrequiredTaken off the delivery by a discount: the delivery price before it is delivery_cost + delivery_discount.
delivery_discountsarray of objectrequiredWhat the delivery discount is made of: the sum of amount equals delivery_discount.
Fields · 6
idintegerrequiredRow of the delivery discount log.
sourcestringrequiredHow the discount got into the order — values as in applied_discounts[].source.
- Values:
promocodeautomaticpickmanualoffline_captureloyalty_programexternal_pos
kindstring or nullrequiredWhat the discount is for — values as in applied_discounts[].kind.
- Values:
promoemployeeexpirypayment_methodmarkdowngoodwillcompothernull
nameobject or nullrequiredName of the rule at the time of sale; null — a promo code discount.
codestring or nullrequiredThe promo code the buyer entered; null — not a promo code discount.
amountintegerrequiredDelivery discount amount.
delivery_tax_linesarray of object or nullrequiredTax of the delivery by the default tax class of the store: its share of the tax of its rate in tax_lines; null when there is no delivery to pay or the tax is unknown.
Fields · 6
regimestringrequiredWhich tax: vat — value added tax (IVA); income — income tax; turnover — gross receipts tax (Ingresos Brutos); municipal — a municipal levy; internal — excise; social — social security; other. Tax of a sale is vat: the tax class of a product classifies value added tax.
- Values:
vatincometurnovermunicipalinternalsocialother
kindstringrequiredtaxed — at the rate; exempt — exempt by law; untaxed — outside the scope of the tax. exempt and untaxed lines have rate_bps 0 and amount 0: the amount is in base.
- Values:
taxedexemptuntaxed
rate_bpsintegerrequiredRate in basis points: 2100 is 21 %.
baseintegerrequiredBase of the tax, without the tax. Prices include tax: base + amount is what the customer paid for this part.
amountintegerrequiredAmount of the tax. The tax of a sale is calculated per rate for the whole order, the base rounded to the nearest unit and the tax as the rest; items and delivery get shares of it, so their lines add up to the line of the order.
jurisdictionstring or nullrequiredProvince or municipality for taxes that need one (turnover, municipal); otherwise null.
platform_discountintegerrequiredDiscount paid by the aggregator platform: it does not reduce the sale of the store.
platform_service_feeintegerrequiredService fee of the aggregator platform: part of total, but not a sale of the store.
platform_delivery_feeintegerrequiredDelivery carried by the aggregator platform: part of total, but not a sale of the store.
totalintegerrequiredAmount of the order to pay.
tax_linesarray of object or nullrequiredTax of the sale by the classification of the products at the time of the sale: the taxable part of the order (items except gift card sales, visits beyond what a package paid, delivery) by rate. For each rate the tax_lines of the items and delivery_tax_lines add up to the line of the order. The legally binding tax is in the fiscal document: the issuing legal entity sets it by its tax status. null when the store has no tax classes or the order has no taxable part.
Fields · 6
regimestringrequiredWhich tax: vat — value added tax (IVA); income — income tax; turnover — gross receipts tax (Ingresos Brutos); municipal — a municipal levy; internal — excise; social — social security; other. Tax of a sale is vat: the tax class of a product classifies value added tax.
- Values:
vatincometurnovermunicipalinternalsocialother
kindstringrequiredtaxed — at the rate; exempt — exempt by law; untaxed — outside the scope of the tax. exempt and untaxed lines have rate_bps 0 and amount 0: the amount is in base.
- Values:
taxedexemptuntaxed
rate_bpsintegerrequiredRate in basis points: 2100 is 21 %.
baseintegerrequiredBase of the tax, without the tax. Prices include tax: base + amount is what the customer paid for this part.
amountintegerrequiredAmount of the tax. The tax of a sale is calculated per rate for the whole order, the base rounded to the nearest unit and the tax as the rest; items and delivery get shares of it, so their lines add up to the line of the order.
jurisdictionstring or nullrequiredProvince or municipality for taxes that need one (turnover, municipal); otherwise null.
gift_card_issue_amountinteger or nullrequiredFace value of the gift card the order sells: a liability of the store, not revenue; null when the order does not sell a gift card.
reservation_deposit_amountinteger or nullrequiredDeposit for a table reservation or a booking: a prepayment, not revenue; null when the order is not a deposit.
account_payment_amountinteger or nullrequiredPayment against the debt of the customer: money received for the debt, not revenue; null when the order is not a debt payment.
service_package_issue_amountinteger or nullrequiredVisit packages sold in the order: the store owes these visits, so it is not revenue — revenue comes when a visit is redeemed from the package; null when the order has no packages.
payment_methodstring or nullrequiredPayment method chosen when the order was placed: manual — a manual method of the store (manual_payment_method_id). The actual payments are in /v1/payments. null when none was chosen.
- Values:
cashmercadopagocryptobybittrc20balancemodopaywaymercadopago_qrmercadopago_pointmercadopago_transfergift_cardsubscriptiondepositexternalmanualoffseton_accountexchange_creditbonpuntoservice_packagenull
manual_payment_method_idinteger or nullrequiredManual payment method of the store (/v1/manual-payment-methods) when payment_method is manual; otherwise null.
delivery_method_idinteger or nullrequiredDelivery method of the store (/v1/delivery-methods); null when the order has none, such as a sale at the register.
fulfilment_typestring or nullrequiredHow the order reaches the customer, by its delivery method at the time of the order: self_pickup — pickup at a location; home_delivery — delivery to an address; parcel_locker — a parcel locker; mail_post — by post; pos — handed over at the register; aggregator — delivered by an aggregator platform; manual_courier — a courier the store arranges itself. null when unknown.
- Values:
self_pickuphome_deliveryparcel_lockermail_postposaggregatormanual_couriernull
delivery_slotsarray of objectrequiredDelivery windows chosen by the customer, by start; empty when there is no window.
Fields · 2
fromstringrequiredStart of the window.
tostringrequiredEnd of the window.
shipmentobject or nullrequiredThe carrier shipment, or the number of a non-integrated delivery service entered by the store; null when the order has none. The label is at GET /v1/orders/{order}/shipment/label when label_available is true.
Fields · 8
carrierstringrequiredThe carrier as a module key: andreani, correo_argentino, uber_direct, mercadolibre (Mercado Envíos); courier_service — a delivery service without integration whose number the store entered (POST /v1/orders/{order}/shipment/tracking), the service is in carrier_name, no statuses.
- Values:
andreanicorreo_argentinouber_directmercadolibrecourier_service
carrier_namestring or nullrequiredThe service as the store named it, for a manually entered number; null for an integrated carrier (carrier names it) or when the store didn't name the service.
tracking_numberstringrequiredThe shipment number at the carrier: it is found in the carrier account and tracked by it.
tracking_urlstring or nullrequiredThe tracking page at the carrier; null when the carrier gave none.
statusstring or nullrequiredThe latest status: accepted — accepted, the parcel is still at the store; preparing — the carrier is preparing the dispatch; courier_assigned — a courier is on the way to pick it up; picked_up — picked up; in_transit — in transit; arrived_at_branch — waiting at a branch; out_for_delivery — with the last-mile courier; delivery_failed — a delivery attempt failed, the carrier will retry; delivered — delivered; not_delivered — the carrier gave up delivering; returned — returned to the sender; lost — lost; cancelled — cancelled; unknown — a carrier status outside this set, its text is in events[].description. null when there is no status yet. A late intermediate status does not undo delivered, cancelled, returned or lost.
- Values:
acceptedpreparingcourier_assignedpicked_upin_transitarrived_at_branchout_for_deliverydelivery_faileddeliverednot_deliveredreturnedlostcancelledunknownnull
status_atstring (date-time) or nullrequiredWhen the latest status happened.
eventsarray of objectrequiredStatus history by the time of the event at the carrier.
Fields · 3
statusstringrequiredThe status — values as in shipment.status.
- Values:
acceptedpreparingcourier_assignedpicked_upin_transitarrived_at_branchout_for_deliverydelivery_faileddeliverednot_deliveredreturnedlostcancelledunknown
descriptionstring or nullrequiredThe status in the carrier's words; null when the carrier gave no text.
occurred_atstring (date-time)requiredWhen the event happened at the carrier.
label_availablebooleanrequiredThe label can be downloaded: the store holds the file or the carrier serves it on request.
previous_shipmentsarray of objectrequiredShipments replaced by a re-issue (the previous one was cancelled and a new one issued), oldest first; same shape as shipment, without label_available.
Fields · 7
carrierstringrequiredThe carrier — values as in shipment.carrier.
- Values:
andreanicorreo_argentinouber_directmercadolibrecourier_service
carrier_namestring or nullrequiredThe service of a manually entered number — as in shipment.carrier_name.
tracking_numberstringrequiredThe shipment number at the carrier.
tracking_urlstring or nullrequiredThe tracking page at the carrier; null when the carrier gave none.
statusstring or nullrequiredThe latest status — values as in shipment.status.
- Values:
acceptedpreparingcourier_assignedpicked_upin_transitarrived_at_branchout_for_deliverydelivery_faileddeliverednot_deliveredreturnedlostcancelledunknownnull
status_atstring (date-time) or nullrequiredWhen the latest status happened.
eventsarray of objectrequiredStatus history by the time of the event at the carrier.
Fields · 3
statusstringrequiredThe status — values as in shipment.status.
- Values:
acceptedpreparingcourier_assignedpicked_upin_transitarrived_at_branchout_for_deliverydelivery_faileddeliverednot_deliveredreturnedlostcancelledunknown
descriptionstring or nullrequiredThe status in the carrier's words; null when the carrier gave no text.
occurred_atstring (date-time)requiredWhen the event happened at the carrier.
shipment_attemptobject or nullrequiredAn unfinished shipment issue; null when there is none.
Fields · 3
statestringrequiredqueued — the issue was requested through the API and is waiting in the queue; in_progress — the request to the carrier is running right now; outcome_unknown — the connection to the carrier dropped after the request, and it is unknown whether the shipment was created: a new issue is blocked until the store checks with the carrier in the panel; failed — the requested issue failed and there is no shipment, the reason is in error.
- Values:
queuedin_progressoutcome_unknownfailed
started_atstring (date-time)requiredWhen the issue was requested or started.
errorobject or nullrequiredWhy the requested issue failed; null unless it failed.
Fields · 2
codestringrequiredThe reason as a machine code: no_carrier — the delivery method has no integrated carrier; not_shippable — the order no longer ships; awaits_bill_payment — the bill is unpaid; carrier_rejected — the carrier refused; shipment_data_invalid — the order data or the carrier settings are incomplete; request_expired — the request was not processed in time; internal_error — a service failure before the carrier was contacted.
- Values:
no_carriernot_shippableawaits_bill_paymentcarrier_rejectedshipment_data_invalidrequest_expiredinternal_error
messagestringrequiredThe reason in the store's words in the response language; when the carrier refused, with its words.
merged_into_order_idinteger or nullrequiredThe order this one was merged into when bills of a table were joined: its items and payments are there, and this order stays an empty cancelled record. null when not merged.
cancel_reasonstring or nullrequiredSystem reason of the cancellation: payment_init_failed — the payment could not start; payment_declined — the payment was declined; cashier_void — voided at the register; shift_closed — the shift of the register closed; order_timeout — not paid in time; merged — merged into another order; items_moved — the items moved to another order; sale_void — the sale was voided; subscription_day_unserved — a day of a subscription was not served; booking_forfeit_reverted — the forfeit of a booking was reverted; service_package_term_extended — a visit package term was extended and its expiry reverted; membership_renewal_void — a membership renewal invoice was voided: the membership was cancelled or ended. null when not cancelled or when a person gave the reason.
- Values:
payment_init_failedpayment_declinedcashier_voidshift_closedorder_timeoutmergeditems_movedsale_voidsubscription_day_unservedbooking_forfeit_revertedservice_package_term_extendedmembership_renewal_voidnull
itemsarray of objectrequiredItems of the order: a historical record, names are as at the time of the sale.
Fields · 15
idintegerrequiredID of the item.
variant_idinteger or nullrequiredVariant of the item; null for an item without a variant, such as a gift card sold at the register.
product_idinteger or nullrequiredProduct of the item; null for an item without a variant.
product_namemap of stringrequiredName of the product at the time of the sale, by language.
variant_namemap of stringrequiredName of the variant at the time of the sale, by language; an empty object when the variant had no name.
quantitystringrequiredQuantity, a decimal string in unit: pieces for an item sold by the piece, the measure for an item sold by weight or volume ("480" grams).
unitstring or nullrequiredUnit of quantity: pcs, g or ml; null when the variant no longer knows the unit of its measure.
- Values:
pcsgmlnull
unit_priceinteger or nullrequiredPrice of one piece; null for an item sold by weight or volume, its amount is in total.
totalintegerrequiredAmount of the item.
discountintegerrequiredDiscount on the item.
discount_allocationsarray of objectrequiredWhich log discounts make up the item's discount: the sum of amount equals items[].discount.
Fields · 2
applied_discount_idintegerrequiredRow of applied_discounts of this order.
amountintegerrequiredThis discount's share on the item.
is_giftbooleanrequiredA gift of a promotion or a promo code: the item is priced and fully discounted.
tax_linesarray of object or nullrequiredTax of the item: its share of the tax of its rate in tax_lines of the order. It covers the taxable part of the item: a visit partly paid by a package counts only the rest. null for an item outside the sale (a gift card sale, a visit fully paid by a package, a fully discounted item) or when the tax is unknown.
Fields · 6
regimestringrequiredWhich tax: vat — value added tax (IVA); income — income tax; turnover — gross receipts tax (Ingresos Brutos); municipal — a municipal levy; internal — excise; social — social security; other. Tax of a sale is vat: the tax class of a product classifies value added tax.
- Values:
vatincometurnovermunicipalinternalsocialother
kindstringrequiredtaxed — at the rate; exempt — exempt by law; untaxed — outside the scope of the tax. exempt and untaxed lines have rate_bps 0 and amount 0: the amount is in base.
- Values:
taxedexemptuntaxed
rate_bpsintegerrequiredRate in basis points: 2100 is 21 %.
baseintegerrequiredBase of the tax, without the tax. Prices include tax: base + amount is what the customer paid for this part.
amountintegerrequiredAmount of the tax. The tax of a sale is calculated per rate for the whole order, the base rounded to the nearest unit and the tax as the rest; items and delivery get shares of it, so their lines add up to the line of the order.
jurisdictionstring or nullrequiredProvince or municipality for taxes that need one (turnover, municipal); otherwise null.
cost_amountinteger or nullCost of the item at the time of the sale: an amount in minor units of currency for the whole item, not a rate. null when it was not calculated. Only with the costs:read scope.
cost_basisstring or nullHow the cost was calculated: variant — the cost of the variant; recipe — the sum of the recipe; standard — by the standard recipe, an estimate; partial — only the known part of the recipe, a lower bound; backfill — estimated later by the catalog cost, not at the time of the sale; external — taken from the external register that made the sale; unknown — nothing to calculate from. Only with the costs:read scope.
- Values:
variantrecipeunknownbackfillstandardpartialexternalnull
customerobject or nullThe customer of the order; null for an order without a customer. Only with the customers:read scope.
Fields · 4
idintegerrequiredID of the record, unique among records of its kind in the store.
namestring or nullrequiredName of the customer; null when unknown.
phonestring or nullrequiredMain phone of the customer in E.164 format, such as +5491123456789; null when unknown.
emailstring or nullrequiredEmail of the customer; null when unknown.
delivery_addressobject or nullDelivery address at the time of the order; null for pickup — the pickup point is location_id. Only with the customers:read scope.
Fields · 16
kindstringrequiredaddress — an address of the customer; branch — a pickup branch of a carrier (branch, address_line).
- Values:
addressbranch
recipientstring or nullrequiredWho receives the order; null when not given.
phonestring or nullrequiredPhone of the recipient; null when not given.
streetstring or nullrequiredStreet.
housestring or nullrequiredHouse number.
apartmentstring or nullrequiredApartment or office.
floorstring or nullrequiredFloor.
entrancestring or nullrequiredEntrance.
districtstring or nullrequiredDistrict or neighborhood.
citystring or nullrequiredCity.
provincestring or nullrequiredProvince or state.
postal_codestring or nullrequiredPostal code.
address_linestring or nullrequiredAddress of the carrier branch in one line; null for an address of the customer.
commentstring or nullrequiredComment of the customer about the address, such as how to get in.
locationobject or nullrequiredPoint of the address on the map; null when unknown.
Fields · 2
latnumberrequiredLatitude in degrees.
lngnumberrequiredLongitude in degrees.
branchobject or nullrequiredThe carrier branch when kind is branch; otherwise null.
Fields · 2
external_idstring or nullrequiredID of the branch in the system of the carrier.
namestring or nullrequiredName of the branch.
customer_commentstring or nullComment of the customer to the order. Only with the customers:read scope.
fiscal_receptorobject or nullWho the fiscal document of the order is issued to, frozen on the order; null for a retail sale without tax details. Only with the customers:read scope.
Fields · 5
id_typestringrequiredKind of ID: tax_id — tax ID of a business (CUIT in Argentina); personal_id — tax ID of a person (CUIL); national_id — national identity document (DNI); passport; none — no ID.
- Values:
tax_idpersonal_idnational_idpassportnone
id_numberstring or nullrequiredNumber of the ID; null when id_type is none.
namestring or nullrequiredLegal or full name for the document; null when not given.
tax_statusstringrequiredTax status: registered — registered for VAT (Responsable Inscripto in Argentina); small_taxpayer — a simplified regime (Monotributo); exempt — exempt from VAT; final_consumer — a final consumer; not_categorized — not categorized; foreign — a foreign customer.
- Values:
registeredsmall_taxpayerexemptfinal_consumernot_categorizedforeign
addressstring or nullrequiredFiscal address in one line; null when not given.
external_fiscal_documentobject or nullThe sale document in an external POS: the order went to the store POS or came from it, and the POS issues the document, not us — such an order has no fiscal documents. null when there is no POS document: the document is ours or the POS did not report it. Only with the fiscal:read scope.
Fields · 3
issuerstringrequiredThe POS that issues the document: fudo is FuDo, poster is Poster.
statusstringrequiredpending: the bill is open in the POS, which issues the document when it closes; issued: the POS issued the document.
- Values:
pendingissued
numberstring or nullrequiredDocument number in the POS; null until the document is issued or when the POS does not report the number.
placed_atstring (date-time)requiredWhen the order was placed.
confirmed_atstring (date-time) or nullrequiredWhen the store confirmed the order; null until then.
completed_atstring (date-time) or nullrequiredWhen the order was completed; null until then.
cancelled_atstring (date-time) or nullrequiredWhen the order was cancelled; null when it was not.
refunded_atstring (date-time) or nullrequiredWhen the order was refunded in full; null when it was not.
created_atstring (date-time)requiredWhen the record was created.
updated_atstring (date-time)requiredWhen the record last changed.
Endpoints
List orders changed since a given time: items, totals, the order status and the payment status
get/orders
Scope: orders:read
Parameters
Query
limitintegerPage size: up to 250 records; 50 by default.
- Minimum:
- 1
- Maximum:
- 250
cursorstringOpaque cursor: next_cursor of the previous page, or sync_cursor of the last page saved by the previous sync. The list goes in commit order, so the sync cursor later returns only what changed after it.
- Max length:
- 4096
updated_sincestring (date-time)Only records changed after this moment, ISO 8601 with a time zone. A filter for the first sync; continue with the cursor.
- Pattern:
^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{1,6})?(Z|[+-]\d{2}:\d{2})$
include_deletedbooleantrue — also return deleted records: archived ones with deleted_at set, and records erased from the database as tombstones {id, deleted_at} in the continuation by the sync cursor. Turn it on for a sync.
numberstringOnly the order with this number.
- Max length:
- 16
Responses
200Success
application/json
Records of the page.
deletedarray of objectrequiredRecords erased from the database since the cursor, as tombstones: only with include_deleted=true in the continuation by the sync cursor.
Fields · 2
idintegerrequiredID of the erased record.
deleted_atstring (date-time)requiredWhen the record was erased.
next_cursorstring or nullrequiredCursor of the next page; null on the last page.
has_morebooleanrequiredtrue when there is a next page.
sync_cursorstring or nullrequiredOn the last page — the cursor to continue from later: it returns only what changed after this page. null on other pages.
401The token is missing, invalid, expired or revoked
Headers
WWW-AuthenticatestringrequiredAuthentication scheme (RFC 6750).
- Example:
Bearer
application/problem+json
Returns Problem
403The plan, the IP address or the token scopes do not allow the request
Headers
WWW-AuthenticatestringAuthentication scheme (RFC 6750).
- Example:
Bearer error="insufficient_scope", scope="locations:read"
application/problem+json
Returns ForbiddenProblem
410The sync cursor is older than the deletion retention period or was issued before the database was restored
application/problem+json
Returns Problem
422A parameter is invalid or unknown
application/problem+json
Returns ValidationProblem
429The rate limit is exhausted
Headers
Retry-AfterintegerrequiredSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns RateLimitProblem
503The store is temporarily unavailable
Headers
Retry-AfterintegerSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns Problem
Errors of this endpoint
Common errors such as token, access, input validation and rate limit can come from any endpoint; they are listed in the catalog: Errors
curl "https://api.saleya.app/v1/orders" \
-H "Authorization: Bearer $SALEYA_API_TOKEN"{
"data": [
{
"id": 0,
"number": "string",
"channel": "web",
"app_id": 0,
"location_id": 0,
"legal_entity_id": 0,
"status": "string",
"status_group": "pos_open",
"payment_status": "unpaid",
"sale_type": "retail",
"currency": "string",
"items_total": 0,
"discount": 0,
"applied_discounts": [
{
"id": 0,
"source": "promocode",
"kind": "promo",
"name": {},
"code": "string",
"reason": "string",
"order_item_id": 0,
"amount": 0
}
],
"delivery_cost": 0,
"delivery_discount": 0,
"delivery_discounts": [
{
"id": 0,
"source": "promocode",
"kind": "promo",
"name": {},
"code": "string",
"amount": 0
}
],
"delivery_tax_lines": [
{
"regime": "vat",
"kind": "taxed",
"rate_bps": 0,
"base": 0,
"amount": 0,
"jurisdiction": "string"
}
],
"platform_discount": 0,
"platform_service_fee": 0,
"platform_delivery_fee": 0,
"total": 0,
"tax_lines": [
{
"regime": "vat",
"kind": "taxed",
"rate_bps": 0,
"base": 0,
"amount": 0,
"jurisdiction": "string"
}
],
"gift_card_issue_amount": 0,
"reservation_deposit_amount": 0,
"account_payment_amount": 0,
"service_package_issue_amount": 0,
"payment_method": "cash",
"manual_payment_method_id": 0,
"delivery_method_id": 0,
"fulfilment_type": "self_pickup",
"delivery_slots": [
{
"from": "string",
"to": "string"
}
],
"shipment": {
"carrier": "andreani",
"carrier_name": "string",
"tracking_number": "string",
"tracking_url": "string",
"status": "accepted",
"status_at": "2026-01-15T12:00:00Z",
"events": [
{
"status": "accepted",
"description": "string",
"occurred_at": "2026-01-15T12:00:00Z"
}
],
"label_available": true
},
"previous_shipments": [
{
"carrier": "andreani",
"carrier_name": "string",
"tracking_number": "string",
"tracking_url": "string",
"status": "accepted",
"status_at": "2026-01-15T12:00:00Z",
"events": [
{
"status": "accepted",
"description": "string",
"occurred_at": "2026-01-15T12:00:00Z"
}
]
}
],
"shipment_attempt": {
"state": "queued",
"started_at": "2026-01-15T12:00:00Z",
"error": {
"code": "no_carrier",
"message": "string"
}
},
"merged_into_order_id": 0,
"cancel_reason": "payment_init_failed",
"items": [
{
"id": 0,
"variant_id": 0,
"product_id": 0,
"product_name": {
"key": "string"
},
"variant_name": {
"key": "string"
},
"quantity": "string",
"unit": "pcs",
"unit_price": 0,
"total": 0,
"discount": 0,
"discount_allocations": [
{
"applied_discount_id": 0,
"amount": 0
}
],
"is_gift": true,
"tax_lines": [
{
"regime": "vat",
"kind": "taxed",
"rate_bps": 0,
"base": 0,
"amount": 0,
"jurisdiction": "string"
}
],
"cost_amount": 0,
"cost_basis": "variant"
}
],
"customer": {
"id": 0,
"name": "string",
"phone": "string",
"email": "string"
},
"delivery_address": {
"kind": "address",
"recipient": "string",
"phone": "string",
"street": "string",
"house": "string",
"apartment": "string",
"floor": "string",
"entrance": "string",
"district": "string",
"city": "string",
"province": "string",
"postal_code": "string",
"address_line": "string",
"comment": "string",
"location": {
"lat": 0,
"lng": 0
},
"branch": {
"external_id": "string",
"name": "string"
}
},
"customer_comment": "string",
"fiscal_receptor": {
"id_type": "tax_id",
"id_number": "string",
"name": "string",
"tax_status": "registered",
"address": "string"
},
"external_fiscal_document": {
"issuer": "string",
"status": "pending",
"number": "string"
},
"placed_at": "2026-01-15T12:00:00Z",
"confirmed_at": "2026-01-15T12:00:00Z",
"completed_at": "2026-01-15T12:00:00Z",
"cancelled_at": "2026-01-15T12:00:00Z",
"refunded_at": "2026-01-15T12:00:00Z",
"created_at": "2026-01-15T12:00:00Z",
"updated_at": "2026-01-15T12:00:00Z"
}
],
"deleted": [
{
"id": 0,
"deleted_at": "2026-01-15T12:00:00Z"
}
],
"next_cursor": "string",
"has_more": true,
"sync_cursor": "string"
}Get an order
get/orders/{order}
Scope: orders:read
Parameters
Path
orderintegerrequiredID of the order.
Responses
200Success
application/json
Returns Order
401The token is missing, invalid, expired or revoked
Headers
WWW-AuthenticatestringrequiredAuthentication scheme (RFC 6750).
- Example:
Bearer
application/problem+json
Returns Problem
403The plan, the IP address or the token scopes do not allow the request
Headers
WWW-AuthenticatestringAuthentication scheme (RFC 6750).
- Example:
Bearer error="insufficient_scope", scope="locations:read"
application/problem+json
Returns ForbiddenProblem
404The object does not exist or is not available to the app
application/problem+json
Returns Problem
422A parameter is invalid or unknown
application/problem+json
Returns ValidationProblem
429The rate limit is exhausted
Headers
Retry-AfterintegerrequiredSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns RateLimitProblem
503The store is temporarily unavailable
Headers
Retry-AfterintegerSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns Problem
Common errors such as token, access, input validation and rate limit can come from any endpoint; they are listed in the catalog: Errors
curl "https://api.saleya.app/v1/orders/{order}" \
-H "Authorization: Bearer $SALEYA_API_TOKEN"{
"id": 0,
"number": "string",
"channel": "web",
"app_id": 0,
"location_id": 0,
"legal_entity_id": 0,
"status": "string",
"status_group": "pos_open",
"payment_status": "unpaid",
"sale_type": "retail",
"currency": "string",
"items_total": 0,
"discount": 0,
"applied_discounts": [
{
"id": 0,
"source": "promocode",
"kind": "promo",
"name": {},
"code": "string",
"reason": "string",
"order_item_id": 0,
"amount": 0
}
],
"delivery_cost": 0,
"delivery_discount": 0,
"delivery_discounts": [
{
"id": 0,
"source": "promocode",
"kind": "promo",
"name": {},
"code": "string",
"amount": 0
}
],
"delivery_tax_lines": [
{
"regime": "vat",
"kind": "taxed",
"rate_bps": 0,
"base": 0,
"amount": 0,
"jurisdiction": "string"
}
],
"platform_discount": 0,
"platform_service_fee": 0,
"platform_delivery_fee": 0,
"total": 0,
"tax_lines": [
{
"regime": "vat",
"kind": "taxed",
"rate_bps": 0,
"base": 0,
"amount": 0,
"jurisdiction": "string"
}
],
"gift_card_issue_amount": 0,
"reservation_deposit_amount": 0,
"account_payment_amount": 0,
"service_package_issue_amount": 0,
"payment_method": "cash",
"manual_payment_method_id": 0,
"delivery_method_id": 0,
"fulfilment_type": "self_pickup",
"delivery_slots": [
{
"from": "string",
"to": "string"
}
],
"shipment": {
"carrier": "andreani",
"carrier_name": "string",
"tracking_number": "string",
"tracking_url": "string",
"status": "accepted",
"status_at": "2026-01-15T12:00:00Z",
"events": [
{
"status": "accepted",
"description": "string",
"occurred_at": "2026-01-15T12:00:00Z"
}
],
"label_available": true
},
"previous_shipments": [
{
"carrier": "andreani",
"carrier_name": "string",
"tracking_number": "string",
"tracking_url": "string",
"status": "accepted",
"status_at": "2026-01-15T12:00:00Z",
"events": [
{
"status": "accepted",
"description": "string",
"occurred_at": "2026-01-15T12:00:00Z"
}
]
}
],
"shipment_attempt": {
"state": "queued",
"started_at": "2026-01-15T12:00:00Z",
"error": {
"code": "no_carrier",
"message": "string"
}
},
"merged_into_order_id": 0,
"cancel_reason": "payment_init_failed",
"items": [
{
"id": 0,
"variant_id": 0,
"product_id": 0,
"product_name": {
"key": "string"
},
"variant_name": {
"key": "string"
},
"quantity": "string",
"unit": "pcs",
"unit_price": 0,
"total": 0,
"discount": 0,
"discount_allocations": [
{
"applied_discount_id": 0,
"amount": 0
}
],
"is_gift": true,
"tax_lines": [
{
"regime": "vat",
"kind": "taxed",
"rate_bps": 0,
"base": 0,
"amount": 0,
"jurisdiction": "string"
}
],
"cost_amount": 0,
"cost_basis": "variant"
}
],
"customer": {
"id": 0,
"name": "string",
"phone": "string",
"email": "string"
},
"delivery_address": {
"kind": "address",
"recipient": "string",
"phone": "string",
"street": "string",
"house": "string",
"apartment": "string",
"floor": "string",
"entrance": "string",
"district": "string",
"city": "string",
"province": "string",
"postal_code": "string",
"address_line": "string",
"comment": "string",
"location": {
"lat": 0,
"lng": 0
},
"branch": {
"external_id": "string",
"name": "string"
}
},
"customer_comment": "string",
"fiscal_receptor": {
"id_type": "tax_id",
"id_number": "string",
"name": "string",
"tax_status": "registered",
"address": "string"
},
"external_fiscal_document": {
"issuer": "string",
"status": "pending",
"number": "string"
},
"placed_at": "2026-01-15T12:00:00Z",
"confirmed_at": "2026-01-15T12:00:00Z",
"completed_at": "2026-01-15T12:00:00Z",
"cancelled_at": "2026-01-15T12:00:00Z",
"refunded_at": "2026-01-15T12:00:00Z",
"created_at": "2026-01-15T12:00:00Z",
"updated_at": "2026-01-15T12:00:00Z"
}Download the carrier label of the order's current shipment as a PDF; it carries the recipient's details, so customers:read is required too
get/orders/{order}/shipment/label
Scope: orders:readcustomers:read
Parameters
Path
orderintegerrequiredID of the order.
Responses
200Success
application/pdf
string (binary)
401The token is missing, invalid, expired or revoked
Headers
WWW-AuthenticatestringrequiredAuthentication scheme (RFC 6750).
- Example:
Bearer
application/problem+json
Returns Problem
403The plan, the IP address or the token scopes do not allow the request
Headers
WWW-AuthenticatestringAuthentication scheme (RFC 6750).
- Example:
Bearer error="insufficient_scope", scope="locations:read"
application/problem+json
Returns ForbiddenProblem
404The object does not exist or is not available to the app
application/problem+json
Returns Problem
409A request with the same idempotency key is in progress, the data changed after it was read, the external ID belongs to another record, the plan or webhook endpoint limit is reached, or the change needs consent to its consequences
Headers
Retry-AfterintegerSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns ConflictProblem
422A parameter is invalid or unknown
application/problem+json
Returns ValidationProblem
429The rate limit is exhausted
Headers
Retry-AfterintegerrequiredSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns RateLimitProblem
503The store is temporarily unavailable
Headers
Retry-AfterintegerSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns Problem
Errors of this endpoint
Common errors such as token, access, input validation and rate limit can come from any endpoint; they are listed in the catalog: Errors
curl "https://api.saleya.app/v1/orders/{order}/shipment/label" \
-H "Authorization: Bearer $SALEYA_API_TOKEN"Move an order to another status of the store
post/orders/{order}/status
Scope: orders:write
Parameters
Path
orderintegerrequiredID of the order.
Header
Idempotency-KeystringUnique key of the attempt, for example a UUID. A retry with the same key and body gets the saved response instead of a second write. Keys live 24 hours.
- Min length:
- 1
- Max length:
- 255
- Example:
8e03978e-40d5-43e8-bc93-6894a57f9324
Request body application/json
statusstringrequiredStatus of the order: a code from the status list of the store (/v1/order-statuses). A store can add its own statuses; status_group gives the lasting meaning.
- Max length:
- 50
commentstring or nullComment to the change, kept in the history of the order.
- Max length:
- 500
delivery_failure_reasonstring or nullFor a move to a status of the delivery_failed group — why: customer_absent — nobody at the address; refused — the customer refused the order; wrong_address — the address was not found; no_contact — the customer could not be reached; other — another reason, explained in comment.
- Values:
customer_absentrefusedwrong_addressno_contactothernull
Responses
200Success
Headers
Idempotent-Replayedstringtrue when this is the saved response of an earlier request with the same Idempotency-Key.
- Values:
true
application/json
Returns Order
401The token is missing, invalid, expired or revoked
Headers
WWW-AuthenticatestringrequiredAuthentication scheme (RFC 6750).
- Example:
Bearer
application/problem+json
Returns Problem
403The plan, the IP address or the token scopes do not allow the request
Headers
WWW-AuthenticatestringAuthentication scheme (RFC 6750).
- Example:
Bearer error="insufficient_scope", scope="locations:read"
application/problem+json
Returns ForbiddenProblem
404The object does not exist or is not available to the app
application/problem+json
Returns Problem
409A request with the same idempotency key is in progress, the data changed after it was read, the external ID belongs to another record, the plan or webhook endpoint limit is reached, or the change needs consent to its consequences
Headers
Retry-AfterintegerSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns ConflictProblem
422A parameter is invalid or unknown
application/problem+json
Returns ValidationProblem
429The rate limit is exhausted
Headers
Retry-AfterintegerrequiredSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns RateLimitProblem
503The store is temporarily unavailable
Headers
Retry-AfterintegerSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns Problem
Errors of this endpoint
- 409
idempotency_key_in_useA request with this key is in progress - 409
order_transition_refusedThe order cannot move to this status - 422
idempotency_key_reusedIdempotency key is already used - 422
invalid_idempotency_keyIdempotency key is invalid
Common errors such as token, access, input validation and rate limit can come from any endpoint; they are listed in the catalog: Errors
curl -X POST "https://api.saleya.app/v1/orders/{order}/status" \
-H "Authorization: Bearer $SALEYA_API_TOKEN" \
-H "Content-Type: application/json" \
-d @body.json{
"status": "string",
"comment": "string",
"delivery_failure_reason": "customer_absent"
}{
"id": 0,
"number": "string",
"channel": "web",
"app_id": 0,
"location_id": 0,
"legal_entity_id": 0,
"status": "string",
"status_group": "pos_open",
"payment_status": "unpaid",
"sale_type": "retail",
"currency": "string",
"items_total": 0,
"discount": 0,
"applied_discounts": [
{
"id": 0,
"source": "promocode",
"kind": "promo",
"name": {},
"code": "string",
"reason": "string",
"order_item_id": 0,
"amount": 0
}
],
"delivery_cost": 0,
"delivery_discount": 0,
"delivery_discounts": [
{
"id": 0,
"source": "promocode",
"kind": "promo",
"name": {},
"code": "string",
"amount": 0
}
],
"delivery_tax_lines": [
{
"regime": "vat",
"kind": "taxed",
"rate_bps": 0,
"base": 0,
"amount": 0,
"jurisdiction": "string"
}
],
"platform_discount": 0,
"platform_service_fee": 0,
"platform_delivery_fee": 0,
"total": 0,
"tax_lines": [
{
"regime": "vat",
"kind": "taxed",
"rate_bps": 0,
"base": 0,
"amount": 0,
"jurisdiction": "string"
}
],
"gift_card_issue_amount": 0,
"reservation_deposit_amount": 0,
"account_payment_amount": 0,
"service_package_issue_amount": 0,
"payment_method": "cash",
"manual_payment_method_id": 0,
"delivery_method_id": 0,
"fulfilment_type": "self_pickup",
"delivery_slots": [
{
"from": "string",
"to": "string"
}
],
"shipment": {
"carrier": "andreani",
"carrier_name": "string",
"tracking_number": "string",
"tracking_url": "string",
"status": "accepted",
"status_at": "2026-01-15T12:00:00Z",
"events": [
{
"status": "accepted",
"description": "string",
"occurred_at": "2026-01-15T12:00:00Z"
}
],
"label_available": true
},
"previous_shipments": [
{
"carrier": "andreani",
"carrier_name": "string",
"tracking_number": "string",
"tracking_url": "string",
"status": "accepted",
"status_at": "2026-01-15T12:00:00Z",
"events": [
{
"status": "accepted",
"description": "string",
"occurred_at": "2026-01-15T12:00:00Z"
}
]
}
],
"shipment_attempt": {
"state": "queued",
"started_at": "2026-01-15T12:00:00Z",
"error": {
"code": "no_carrier",
"message": "string"
}
},
"merged_into_order_id": 0,
"cancel_reason": "payment_init_failed",
"items": [
{
"id": 0,
"variant_id": 0,
"product_id": 0,
"product_name": {
"key": "string"
},
"variant_name": {
"key": "string"
},
"quantity": "string",
"unit": "pcs",
"unit_price": 0,
"total": 0,
"discount": 0,
"discount_allocations": [
{
"applied_discount_id": 0,
"amount": 0
}
],
"is_gift": true,
"tax_lines": [
{
"regime": "vat",
"kind": "taxed",
"rate_bps": 0,
"base": 0,
"amount": 0,
"jurisdiction": "string"
}
],
"cost_amount": 0,
"cost_basis": "variant"
}
],
"customer": {
"id": 0,
"name": "string",
"phone": "string",
"email": "string"
},
"delivery_address": {
"kind": "address",
"recipient": "string",
"phone": "string",
"street": "string",
"house": "string",
"apartment": "string",
"floor": "string",
"entrance": "string",
"district": "string",
"city": "string",
"province": "string",
"postal_code": "string",
"address_line": "string",
"comment": "string",
"location": {
"lat": 0,
"lng": 0
},
"branch": {
"external_id": "string",
"name": "string"
}
},
"customer_comment": "string",
"fiscal_receptor": {
"id_type": "tax_id",
"id_number": "string",
"name": "string",
"tax_status": "registered",
"address": "string"
},
"external_fiscal_document": {
"issuer": "string",
"status": "pending",
"number": "string"
},
"placed_at": "2026-01-15T12:00:00Z",
"confirmed_at": "2026-01-15T12:00:00Z",
"completed_at": "2026-01-15T12:00:00Z",
"cancelled_at": "2026-01-15T12:00:00Z",
"refunded_at": "2026-01-15T12:00:00Z",
"created_at": "2026-01-15T12:00:00Z",
"updated_at": "2026-01-15T12:00:00Z"
}Cancel an order
post/orders/{order}/cancel
Scope: orders:write
Parameters
Path
orderintegerrequiredID of the order.
Query
consentobjectConsents to the consequences of the change, by kind: consent[<consent_kind>]=<consent_token> from a 409 consent_required response. Keep the consents already given when the next kind is asked.
Fields · 1
order_cancelstringCancelling the order returns the received money to the customer, the subscription or the booking, issues a credit note for the fiscal document, cancels the carrier shipment and leaves already picked goods as losses.
- Min length:
- 64
- Max length:
- 64
Header
Idempotency-KeystringUnique key of the attempt, for example a UUID. A retry with the same key and body gets the saved response instead of a second write. Keys live 24 hours.
- Min length:
- 1
- Max length:
- 255
- Example:
8e03978e-40d5-43e8-bc93-6894a57f9324
Request body application/json
statusstringStatus of the order: a code from the status list of the store (/v1/order-statuses). A store can add its own statuses; status_group gives the lasting meaning.
- Max length:
- 50
commentstring or nullReason of the cancellation in words, kept in the history of the order.
- Max length:
- 500
Responses
200Success
Headers
Idempotent-Replayedstringtrue when this is the saved response of an earlier request with the same Idempotency-Key.
- Values:
true
application/json
Returns Order
401The token is missing, invalid, expired or revoked
Headers
WWW-AuthenticatestringrequiredAuthentication scheme (RFC 6750).
- Example:
Bearer
application/problem+json
Returns Problem
403The plan, the IP address or the token scopes do not allow the request
Headers
WWW-AuthenticatestringAuthentication scheme (RFC 6750).
- Example:
Bearer error="insufficient_scope", scope="locations:read"
application/problem+json
Returns ForbiddenProblem
404The object does not exist or is not available to the app
application/problem+json
Returns Problem
409A request with the same idempotency key is in progress, the data changed after it was read, the external ID belongs to another record, the plan or webhook endpoint limit is reached, or the change needs consent to its consequences
Headers
Retry-AfterintegerSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns ConflictProblem
422A parameter is invalid or unknown
application/problem+json
Returns ValidationProblem
429The rate limit is exhausted
Headers
Retry-AfterintegerrequiredSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns RateLimitProblem
503The store is temporarily unavailable
Headers
Retry-AfterintegerSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns Problem
Errors of this endpoint
- 409
consent_requiredConsent to the consequences is required - 409
idempotency_key_in_useA request with this key is in progress - 409
order_cancel_refusedThe order cannot be cancelled - 422
idempotency_key_reusedIdempotency key is already used - 422
invalid_idempotency_keyIdempotency key is invalid
Common errors such as token, access, input validation and rate limit can come from any endpoint; they are listed in the catalog: Errors
curl -X POST "https://api.saleya.app/v1/orders/{order}/cancel" \
-H "Authorization: Bearer $SALEYA_API_TOKEN" \
-H "Content-Type: application/json" \
-d @body.json{
"status": "string",
"comment": "string"
}{
"id": 0,
"number": "string",
"channel": "web",
"app_id": 0,
"location_id": 0,
"legal_entity_id": 0,
"status": "string",
"status_group": "pos_open",
"payment_status": "unpaid",
"sale_type": "retail",
"currency": "string",
"items_total": 0,
"discount": 0,
"applied_discounts": [
{
"id": 0,
"source": "promocode",
"kind": "promo",
"name": {},
"code": "string",
"reason": "string",
"order_item_id": 0,
"amount": 0
}
],
"delivery_cost": 0,
"delivery_discount": 0,
"delivery_discounts": [
{
"id": 0,
"source": "promocode",
"kind": "promo",
"name": {},
"code": "string",
"amount": 0
}
],
"delivery_tax_lines": [
{
"regime": "vat",
"kind": "taxed",
"rate_bps": 0,
"base": 0,
"amount": 0,
"jurisdiction": "string"
}
],
"platform_discount": 0,
"platform_service_fee": 0,
"platform_delivery_fee": 0,
"total": 0,
"tax_lines": [
{
"regime": "vat",
"kind": "taxed",
"rate_bps": 0,
"base": 0,
"amount": 0,
"jurisdiction": "string"
}
],
"gift_card_issue_amount": 0,
"reservation_deposit_amount": 0,
"account_payment_amount": 0,
"service_package_issue_amount": 0,
"payment_method": "cash",
"manual_payment_method_id": 0,
"delivery_method_id": 0,
"fulfilment_type": "self_pickup",
"delivery_slots": [
{
"from": "string",
"to": "string"
}
],
"shipment": {
"carrier": "andreani",
"carrier_name": "string",
"tracking_number": "string",
"tracking_url": "string",
"status": "accepted",
"status_at": "2026-01-15T12:00:00Z",
"events": [
{
"status": "accepted",
"description": "string",
"occurred_at": "2026-01-15T12:00:00Z"
}
],
"label_available": true
},
"previous_shipments": [
{
"carrier": "andreani",
"carrier_name": "string",
"tracking_number": "string",
"tracking_url": "string",
"status": "accepted",
"status_at": "2026-01-15T12:00:00Z",
"events": [
{
"status": "accepted",
"description": "string",
"occurred_at": "2026-01-15T12:00:00Z"
}
]
}
],
"shipment_attempt": {
"state": "queued",
"started_at": "2026-01-15T12:00:00Z",
"error": {
"code": "no_carrier",
"message": "string"
}
},
"merged_into_order_id": 0,
"cancel_reason": "payment_init_failed",
"items": [
{
"id": 0,
"variant_id": 0,
"product_id": 0,
"product_name": {
"key": "string"
},
"variant_name": {
"key": "string"
},
"quantity": "string",
"unit": "pcs",
"unit_price": 0,
"total": 0,
"discount": 0,
"discount_allocations": [
{
"applied_discount_id": 0,
"amount": 0
}
],
"is_gift": true,
"tax_lines": [
{
"regime": "vat",
"kind": "taxed",
"rate_bps": 0,
"base": 0,
"amount": 0,
"jurisdiction": "string"
}
],
"cost_amount": 0,
"cost_basis": "variant"
}
],
"customer": {
"id": 0,
"name": "string",
"phone": "string",
"email": "string"
},
"delivery_address": {
"kind": "address",
"recipient": "string",
"phone": "string",
"street": "string",
"house": "string",
"apartment": "string",
"floor": "string",
"entrance": "string",
"district": "string",
"city": "string",
"province": "string",
"postal_code": "string",
"address_line": "string",
"comment": "string",
"location": {
"lat": 0,
"lng": 0
},
"branch": {
"external_id": "string",
"name": "string"
}
},
"customer_comment": "string",
"fiscal_receptor": {
"id_type": "tax_id",
"id_number": "string",
"name": "string",
"tax_status": "registered",
"address": "string"
},
"external_fiscal_document": {
"issuer": "string",
"status": "pending",
"number": "string"
},
"placed_at": "2026-01-15T12:00:00Z",
"confirmed_at": "2026-01-15T12:00:00Z",
"completed_at": "2026-01-15T12:00:00Z",
"cancelled_at": "2026-01-15T12:00:00Z",
"refunded_at": "2026-01-15T12:00:00Z",
"created_at": "2026-01-15T12:00:00Z",
"updated_at": "2026-01-15T12:00:00Z"
}Issue the order's shipment with its carrier: the request runs in the background, the outcome shows in the order and arrives with order.updated
post/orders/{order}/shipment
Scope: orders:write
Parameters
Path
orderintegerrequiredID of the order.
Header
Idempotency-KeystringUnique key of the attempt, for example a UUID. A retry with the same key and body gets the saved response instead of a second write. Keys live 24 hours.
- Min length:
- 1
- Max length:
- 255
- Example:
8e03978e-40d5-43e8-bc93-6894a57f9324
Responses
200Success
Headers
Idempotent-Replayedstringtrue when this is the saved response of an earlier request with the same Idempotency-Key.
- Values:
true
application/json
Returns Order
202Accepted: the outcome is at the Location URL
Headers
Idempotent-Replayedstringtrue when this is the saved response of an earlier request with the same Idempotency-Key.
- Values:
true
Locationstring (uri)requiredAddress of the created record; for an accepted request (202), the address to follow its outcome.
application/json
Returns Order
401The token is missing, invalid, expired or revoked
Headers
WWW-AuthenticatestringrequiredAuthentication scheme (RFC 6750).
- Example:
Bearer
application/problem+json
Returns Problem
403The plan, the IP address or the token scopes do not allow the request
Headers
WWW-AuthenticatestringAuthentication scheme (RFC 6750).
- Example:
Bearer error="insufficient_scope", scope="locations:read"
application/problem+json
Returns ForbiddenProblem
404The object does not exist or is not available to the app
application/problem+json
Returns Problem
409A request with the same idempotency key is in progress, the data changed after it was read, the external ID belongs to another record, the plan or webhook endpoint limit is reached, or the change needs consent to its consequences
Headers
Retry-AfterintegerSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns ConflictProblem
422A parameter is invalid or unknown
application/problem+json
Returns ValidationProblem
429The rate limit is exhausted
Headers
Retry-AfterintegerrequiredSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns RateLimitProblem
503The store is temporarily unavailable
Headers
Retry-AfterintegerSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns Problem
Errors of this endpoint
- 409
idempotency_key_in_useA request with this key is in progress - 409
shipment_in_progressA shipment issue is already under way - 409
shipment_outcome_unknownThe previous issue has an unknown outcome - 409
shipment_refusedThe shipment cannot be issued now - 422
idempotency_key_reusedIdempotency key is already used - 422
invalid_idempotency_keyIdempotency key is invalid
Common errors such as token, access, input validation and rate limit can come from any endpoint; they are listed in the catalog: Errors
curl -X POST "https://api.saleya.app/v1/orders/{order}/shipment" \
-H "Authorization: Bearer $SALEYA_API_TOKEN"{
"id": 0,
"number": "string",
"channel": "web",
"app_id": 0,
"location_id": 0,
"legal_entity_id": 0,
"status": "string",
"status_group": "pos_open",
"payment_status": "unpaid",
"sale_type": "retail",
"currency": "string",
"items_total": 0,
"discount": 0,
"applied_discounts": [
{
"id": 0,
"source": "promocode",
"kind": "promo",
"name": {},
"code": "string",
"reason": "string",
"order_item_id": 0,
"amount": 0
}
],
"delivery_cost": 0,
"delivery_discount": 0,
"delivery_discounts": [
{
"id": 0,
"source": "promocode",
"kind": "promo",
"name": {},
"code": "string",
"amount": 0
}
],
"delivery_tax_lines": [
{
"regime": "vat",
"kind": "taxed",
"rate_bps": 0,
"base": 0,
"amount": 0,
"jurisdiction": "string"
}
],
"platform_discount": 0,
"platform_service_fee": 0,
"platform_delivery_fee": 0,
"total": 0,
"tax_lines": [
{
"regime": "vat",
"kind": "taxed",
"rate_bps": 0,
"base": 0,
"amount": 0,
"jurisdiction": "string"
}
],
"gift_card_issue_amount": 0,
"reservation_deposit_amount": 0,
"account_payment_amount": 0,
"service_package_issue_amount": 0,
"payment_method": "cash",
"manual_payment_method_id": 0,
"delivery_method_id": 0,
"fulfilment_type": "self_pickup",
"delivery_slots": [
{
"from": "string",
"to": "string"
}
],
"shipment": {
"carrier": "andreani",
"carrier_name": "string",
"tracking_number": "string",
"tracking_url": "string",
"status": "accepted",
"status_at": "2026-01-15T12:00:00Z",
"events": [
{
"status": "accepted",
"description": "string",
"occurred_at": "2026-01-15T12:00:00Z"
}
],
"label_available": true
},
"previous_shipments": [
{
"carrier": "andreani",
"carrier_name": "string",
"tracking_number": "string",
"tracking_url": "string",
"status": "accepted",
"status_at": "2026-01-15T12:00:00Z",
"events": [
{
"status": "accepted",
"description": "string",
"occurred_at": "2026-01-15T12:00:00Z"
}
]
}
],
"shipment_attempt": {
"state": "queued",
"started_at": "2026-01-15T12:00:00Z",
"error": {
"code": "no_carrier",
"message": "string"
}
},
"merged_into_order_id": 0,
"cancel_reason": "payment_init_failed",
"items": [
{
"id": 0,
"variant_id": 0,
"product_id": 0,
"product_name": {
"key": "string"
},
"variant_name": {
"key": "string"
},
"quantity": "string",
"unit": "pcs",
"unit_price": 0,
"total": 0,
"discount": 0,
"discount_allocations": [
{
"applied_discount_id": 0,
"amount": 0
}
],
"is_gift": true,
"tax_lines": [
{
"regime": "vat",
"kind": "taxed",
"rate_bps": 0,
"base": 0,
"amount": 0,
"jurisdiction": "string"
}
],
"cost_amount": 0,
"cost_basis": "variant"
}
],
"customer": {
"id": 0,
"name": "string",
"phone": "string",
"email": "string"
},
"delivery_address": {
"kind": "address",
"recipient": "string",
"phone": "string",
"street": "string",
"house": "string",
"apartment": "string",
"floor": "string",
"entrance": "string",
"district": "string",
"city": "string",
"province": "string",
"postal_code": "string",
"address_line": "string",
"comment": "string",
"location": {
"lat": 0,
"lng": 0
},
"branch": {
"external_id": "string",
"name": "string"
}
},
"customer_comment": "string",
"fiscal_receptor": {
"id_type": "tax_id",
"id_number": "string",
"name": "string",
"tax_status": "registered",
"address": "string"
},
"external_fiscal_document": {
"issuer": "string",
"status": "pending",
"number": "string"
},
"placed_at": "2026-01-15T12:00:00Z",
"confirmed_at": "2026-01-15T12:00:00Z",
"completed_at": "2026-01-15T12:00:00Z",
"cancelled_at": "2026-01-15T12:00:00Z",
"refunded_at": "2026-01-15T12:00:00Z",
"created_at": "2026-01-15T12:00:00Z",
"updated_at": "2026-01-15T12:00:00Z"
}Write the tracking number of a delivery service without integration: number, link and service name
post/orders/{order}/shipment/tracking
Scope: orders:write
Parameters
Path
orderintegerrequiredID of the order.
Header
Idempotency-KeystringUnique key of the attempt, for example a UUID. A retry with the same key and body gets the saved response instead of a second write. Keys live 24 hours.
- Min length:
- 1
- Max length:
- 255
- Example:
8e03978e-40d5-43e8-bc93-6894a57f9324
Request body application/json
tracking_numberstringrequiredThe number at the delivery service: letters and digits, with spaces, dots, slashes, hyphens and underscores allowed inside; up to 64 characters.
- Max length:
- 64
- Pattern:
^[\p{L}\p{N}](?:[\p{L}\p{N} .\/_-]*[\p{L}\p{N}])?$
tracking_urlstring (uri) or nullThe service's tracking page, http or https; null or absent — no link.
- Max length:
- 500
carrier_namestring or nullThe service name as the customer will see it: “Correo Argentino”, “OCA”; null or absent — no name.
- Max length:
- 100
Responses
200Success
Headers
Idempotent-Replayedstringtrue when this is the saved response of an earlier request with the same Idempotency-Key.
- Values:
true
application/json
Returns Order
401The token is missing, invalid, expired or revoked
Headers
WWW-AuthenticatestringrequiredAuthentication scheme (RFC 6750).
- Example:
Bearer
application/problem+json
Returns Problem
403The plan, the IP address or the token scopes do not allow the request
Headers
WWW-AuthenticatestringAuthentication scheme (RFC 6750).
- Example:
Bearer error="insufficient_scope", scope="locations:read"
application/problem+json
Returns ForbiddenProblem
404The object does not exist or is not available to the app
application/problem+json
Returns Problem
409A request with the same idempotency key is in progress, the data changed after it was read, the external ID belongs to another record, the plan or webhook endpoint limit is reached, or the change needs consent to its consequences
Headers
Retry-AfterintegerSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns ConflictProblem
422A parameter is invalid or unknown
application/problem+json
Returns ValidationProblem
429The rate limit is exhausted
Headers
Retry-AfterintegerrequiredSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns RateLimitProblem
503The store is temporarily unavailable
Headers
Retry-AfterintegerSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns Problem
Errors of this endpoint
- 409
idempotency_key_in_useA request with this key is in progress - 409
shipment_in_progressA shipment issue is already under way - 409
shipment_tracking_refusedThe tracking number can't be written manually - 422
idempotency_key_reusedIdempotency key is already used - 422
invalid_idempotency_keyIdempotency key is invalid
Common errors such as token, access, input validation and rate limit can come from any endpoint; they are listed in the catalog: Errors
curl -X POST "https://api.saleya.app/v1/orders/{order}/shipment/tracking" \
-H "Authorization: Bearer $SALEYA_API_TOKEN" \
-H "Content-Type: application/json" \
-d @body.json{
"tracking_number": "string",
"tracking_url": "string",
"carrier_name": "string"
}{
"id": 0,
"number": "string",
"channel": "web",
"app_id": 0,
"location_id": 0,
"legal_entity_id": 0,
"status": "string",
"status_group": "pos_open",
"payment_status": "unpaid",
"sale_type": "retail",
"currency": "string",
"items_total": 0,
"discount": 0,
"applied_discounts": [
{
"id": 0,
"source": "promocode",
"kind": "promo",
"name": {},
"code": "string",
"reason": "string",
"order_item_id": 0,
"amount": 0
}
],
"delivery_cost": 0,
"delivery_discount": 0,
"delivery_discounts": [
{
"id": 0,
"source": "promocode",
"kind": "promo",
"name": {},
"code": "string",
"amount": 0
}
],
"delivery_tax_lines": [
{
"regime": "vat",
"kind": "taxed",
"rate_bps": 0,
"base": 0,
"amount": 0,
"jurisdiction": "string"
}
],
"platform_discount": 0,
"platform_service_fee": 0,
"platform_delivery_fee": 0,
"total": 0,
"tax_lines": [
{
"regime": "vat",
"kind": "taxed",
"rate_bps": 0,
"base": 0,
"amount": 0,
"jurisdiction": "string"
}
],
"gift_card_issue_amount": 0,
"reservation_deposit_amount": 0,
"account_payment_amount": 0,
"service_package_issue_amount": 0,
"payment_method": "cash",
"manual_payment_method_id": 0,
"delivery_method_id": 0,
"fulfilment_type": "self_pickup",
"delivery_slots": [
{
"from": "string",
"to": "string"
}
],
"shipment": {
"carrier": "andreani",
"carrier_name": "string",
"tracking_number": "string",
"tracking_url": "string",
"status": "accepted",
"status_at": "2026-01-15T12:00:00Z",
"events": [
{
"status": "accepted",
"description": "string",
"occurred_at": "2026-01-15T12:00:00Z"
}
],
"label_available": true
},
"previous_shipments": [
{
"carrier": "andreani",
"carrier_name": "string",
"tracking_number": "string",
"tracking_url": "string",
"status": "accepted",
"status_at": "2026-01-15T12:00:00Z",
"events": [
{
"status": "accepted",
"description": "string",
"occurred_at": "2026-01-15T12:00:00Z"
}
]
}
],
"shipment_attempt": {
"state": "queued",
"started_at": "2026-01-15T12:00:00Z",
"error": {
"code": "no_carrier",
"message": "string"
}
},
"merged_into_order_id": 0,
"cancel_reason": "payment_init_failed",
"items": [
{
"id": 0,
"variant_id": 0,
"product_id": 0,
"product_name": {
"key": "string"
},
"variant_name": {
"key": "string"
},
"quantity": "string",
"unit": "pcs",
"unit_price": 0,
"total": 0,
"discount": 0,
"discount_allocations": [
{
"applied_discount_id": 0,
"amount": 0
}
],
"is_gift": true,
"tax_lines": [
{
"regime": "vat",
"kind": "taxed",
"rate_bps": 0,
"base": 0,
"amount": 0,
"jurisdiction": "string"
}
],
"cost_amount": 0,
"cost_basis": "variant"
}
],
"customer": {
"id": 0,
"name": "string",
"phone": "string",
"email": "string"
},
"delivery_address": {
"kind": "address",
"recipient": "string",
"phone": "string",
"street": "string",
"house": "string",
"apartment": "string",
"floor": "string",
"entrance": "string",
"district": "string",
"city": "string",
"province": "string",
"postal_code": "string",
"address_line": "string",
"comment": "string",
"location": {
"lat": 0,
"lng": 0
},
"branch": {
"external_id": "string",
"name": "string"
}
},
"customer_comment": "string",
"fiscal_receptor": {
"id_type": "tax_id",
"id_number": "string",
"name": "string",
"tax_status": "registered",
"address": "string"
},
"external_fiscal_document": {
"issuer": "string",
"status": "pending",
"number": "string"
},
"placed_at": "2026-01-15T12:00:00Z",
"confirmed_at": "2026-01-15T12:00:00Z",
"completed_at": "2026-01-15T12:00:00Z",
"cancelled_at": "2026-01-15T12:00:00Z",
"refunded_at": "2026-01-15T12:00:00Z",
"created_at": "2026-01-15T12:00:00Z",
"updated_at": "2026-01-15T12:00:00Z"
}Remove a manually written tracking number
post/orders/{order}/shipment/tracking/clear
Scope: orders:write
Parameters
Path
orderintegerrequiredID of the order.
Header
Idempotency-KeystringUnique key of the attempt, for example a UUID. A retry with the same key and body gets the saved response instead of a second write. Keys live 24 hours.
- Min length:
- 1
- Max length:
- 255
- Example:
8e03978e-40d5-43e8-bc93-6894a57f9324
Responses
200Success
Headers
Idempotent-Replayedstringtrue when this is the saved response of an earlier request with the same Idempotency-Key.
- Values:
true
application/json
Returns Order
401The token is missing, invalid, expired or revoked
Headers
WWW-AuthenticatestringrequiredAuthentication scheme (RFC 6750).
- Example:
Bearer
application/problem+json
Returns Problem
403The plan, the IP address or the token scopes do not allow the request
Headers
WWW-AuthenticatestringAuthentication scheme (RFC 6750).
- Example:
Bearer error="insufficient_scope", scope="locations:read"
application/problem+json
Returns ForbiddenProblem
404The object does not exist or is not available to the app
application/problem+json
Returns Problem
409A request with the same idempotency key is in progress, the data changed after it was read, the external ID belongs to another record, the plan or webhook endpoint limit is reached, or the change needs consent to its consequences
Headers
Retry-AfterintegerSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns ConflictProblem
422A parameter is invalid or unknown
application/problem+json
Returns ValidationProblem
429The rate limit is exhausted
Headers
Retry-AfterintegerrequiredSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns RateLimitProblem
503The store is temporarily unavailable
Headers
Retry-AfterintegerSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns Problem
Errors of this endpoint
- 409
idempotency_key_in_useA request with this key is in progress - 409
shipment_in_progressA shipment issue is already under way - 409
shipment_tracking_refusedThe tracking number can't be written manually - 422
idempotency_key_reusedIdempotency key is already used - 422
invalid_idempotency_keyIdempotency key is invalid
Common errors such as token, access, input validation and rate limit can come from any endpoint; they are listed in the catalog: Errors
curl -X POST "https://api.saleya.app/v1/orders/{order}/shipment/tracking/clear" \
-H "Authorization: Bearer $SALEYA_API_TOKEN"{
"id": 0,
"number": "string",
"channel": "web",
"app_id": 0,
"location_id": 0,
"legal_entity_id": 0,
"status": "string",
"status_group": "pos_open",
"payment_status": "unpaid",
"sale_type": "retail",
"currency": "string",
"items_total": 0,
"discount": 0,
"applied_discounts": [
{
"id": 0,
"source": "promocode",
"kind": "promo",
"name": {},
"code": "string",
"reason": "string",
"order_item_id": 0,
"amount": 0
}
],
"delivery_cost": 0,
"delivery_discount": 0,
"delivery_discounts": [
{
"id": 0,
"source": "promocode",
"kind": "promo",
"name": {},
"code": "string",
"amount": 0
}
],
"delivery_tax_lines": [
{
"regime": "vat",
"kind": "taxed",
"rate_bps": 0,
"base": 0,
"amount": 0,
"jurisdiction": "string"
}
],
"platform_discount": 0,
"platform_service_fee": 0,
"platform_delivery_fee": 0,
"total": 0,
"tax_lines": [
{
"regime": "vat",
"kind": "taxed",
"rate_bps": 0,
"base": 0,
"amount": 0,
"jurisdiction": "string"
}
],
"gift_card_issue_amount": 0,
"reservation_deposit_amount": 0,
"account_payment_amount": 0,
"service_package_issue_amount": 0,
"payment_method": "cash",
"manual_payment_method_id": 0,
"delivery_method_id": 0,
"fulfilment_type": "self_pickup",
"delivery_slots": [
{
"from": "string",
"to": "string"
}
],
"shipment": {
"carrier": "andreani",
"carrier_name": "string",
"tracking_number": "string",
"tracking_url": "string",
"status": "accepted",
"status_at": "2026-01-15T12:00:00Z",
"events": [
{
"status": "accepted",
"description": "string",
"occurred_at": "2026-01-15T12:00:00Z"
}
],
"label_available": true
},
"previous_shipments": [
{
"carrier": "andreani",
"carrier_name": "string",
"tracking_number": "string",
"tracking_url": "string",
"status": "accepted",
"status_at": "2026-01-15T12:00:00Z",
"events": [
{
"status": "accepted",
"description": "string",
"occurred_at": "2026-01-15T12:00:00Z"
}
]
}
],
"shipment_attempt": {
"state": "queued",
"started_at": "2026-01-15T12:00:00Z",
"error": {
"code": "no_carrier",
"message": "string"
}
},
"merged_into_order_id": 0,
"cancel_reason": "payment_init_failed",
"items": [
{
"id": 0,
"variant_id": 0,
"product_id": 0,
"product_name": {
"key": "string"
},
"variant_name": {
"key": "string"
},
"quantity": "string",
"unit": "pcs",
"unit_price": 0,
"total": 0,
"discount": 0,
"discount_allocations": [
{
"applied_discount_id": 0,
"amount": 0
}
],
"is_gift": true,
"tax_lines": [
{
"regime": "vat",
"kind": "taxed",
"rate_bps": 0,
"base": 0,
"amount": 0,
"jurisdiction": "string"
}
],
"cost_amount": 0,
"cost_basis": "variant"
}
],
"customer": {
"id": 0,
"name": "string",
"phone": "string",
"email": "string"
},
"delivery_address": {
"kind": "address",
"recipient": "string",
"phone": "string",
"street": "string",
"house": "string",
"apartment": "string",
"floor": "string",
"entrance": "string",
"district": "string",
"city": "string",
"province": "string",
"postal_code": "string",
"address_line": "string",
"comment": "string",
"location": {
"lat": 0,
"lng": 0
},
"branch": {
"external_id": "string",
"name": "string"
}
},
"customer_comment": "string",
"fiscal_receptor": {
"id_type": "tax_id",
"id_number": "string",
"name": "string",
"tax_status": "registered",
"address": "string"
},
"external_fiscal_document": {
"issuer": "string",
"status": "pending",
"number": "string"
},
"placed_at": "2026-01-15T12:00:00Z",
"confirmed_at": "2026-01-15T12:00:00Z",
"completed_at": "2026-01-15T12:00:00Z",
"cancelled_at": "2026-01-15T12:00:00Z",
"refunded_at": "2026-01-15T12:00:00Z",
"created_at": "2026-01-15T12:00:00Z",
"updated_at": "2026-01-15T12:00:00Z"
}