Things to know about orders
What every integration should know before reading or importing orders: what an order contains, its lifecycle status, the three statuses of a shipping and the kinds of order lines, coupons included.
What an order contains
The Order object is the root of everything the API exposes about a purchase. Its main parts:
- Identifiers:
numberis the identifier assigned by the integration that submitted the order,deliveryIdthe one the customer sees in the e-shop (in almost all cases the same value);channelis the sales channel the order belongs to. status: where the order is in its lifecycle, see Order statuses below.lines: what was bought, oneOrderLineper product, cost or discount, withkind, quantity, unit prices and VAT, see Order line kinds below.billing: the billing address and fiscal data of the customer (Billing), one per order.shippings: the destinations of the goods, oneShippingeach; an order can have more than one. A shipping carries the recipient address, the carrier and tracking data, its three statuses (see Shipping statuses below), thewarehouseit ships from, the item quantities it dispatches (itemLines), itsparcelsand its documents: the shippinglabels(waybills: one per parcel or a single one for all the parcels, depending on the carrier) and theproforma.- Totals:
totalNetAmount,totalVatAmountandtotalGrossAmountare computed by OMS from the lines;totalPaidAmountis what the customer actually paid, as submitted at import. - Documents:
accountingDocumentsare the fiscal documents issued for the order (receipt, invoice),fiscalDocumentthe latest of them, see Get order documents. - Related records:
saleTransactionsare the payment transactions linked to the order (see Payments),repaymentRequestsits returns (see Repayments). - Dates:
createdAtis when the order was placed on the channel,receivedAtwhen OMS received it,paidAtandcancelledAtwhen it was paid or cancelled.
The Order reference documents every field; Get order details shows a complete query.
Order statuses
An order exposes a single OrderStatus through Order.status: the lifecycle of the order inside OMS. Typical progression:
The meaning of each status is documented on the OrderStatus enum reference. OMS can notify your integration every time an order enters a status — see the Order status change webhook events.
Three things to keep in mind when reacting to a status:
with_anomaliesis where an order waits. It covers a payment not received yet (offline methods such as bank transfer), a failed fraud check or inconsistent order data; the Calicantus customer care resolves it and may correct the order data in the process (billing or shipping data, line amounts), never the products and quantities ordered. Read the order again when it leaves the status instead of assuming that onlystatuschanged.cancelledandrefundedare the two ways an order ends without being processed. Both are reached fromwith_anomaliesand differ only by whether a payment had been received and refunded: in both cases the goods are never shipped.- A
completedorder is never cancelled or refunded. A cancellation requested by the customer from that point on is a repayment request (return) with the reason "Customer cancelled" and the order keeps its status: readOrder.repaymentRequeststo detect it. When the cancellation is accepted before the shipping is handed to the carrier the goods never leave the warehouse, so the request carries no return shipping.
What happens right after an order is submitted — the asynchronous checks that run while it is acquiring, and how with_anomalies is handled — is documented in Import an order.
Shipping statuses
Each entry in Order.shippings carries three independent statuses: status (the carrier tracking state), fulfillmentStatus (the warehouse fulfilment state) and bookingStatus (the shipping label booking state). fulfillmentStatus and status cover two consecutive stages of the flow: a shipping is first fulfilled by the warehouse, and only then shipped by the carrier. bookingStatus tracks the booking process that produces the shipping label (waybill). They are independent state machines: always read the field that answers your question instead of deducing one state from another.
Shipping.status — carrier tracking
Reflects the carrier tracking state of the parcel. The meaning of each state is documented on the ShippingStatus enum reference; it is null until the first tracking information is received from the carrier. delivered and failed are final. When the shipping is handled by an external carrier (bookingStatus: unmanaged), the tracking information and the events are reported through the API — see Report the tracking of a shipping.
Shipping.fulfillmentStatus — warehouse fulfilment
Reflects how much of the shipping has been fulfilled by the warehouse. The meaning of each value is documented on the ShippingFulfillmentStatus enum reference. In projects where the external warehouse validates the shippings, the warehouse moves it from pending to completed, partial or cancelled itself — see Confirm or cancel a fulfilment.
Shipping.bookingStatus — shipping label booking
Reflects the state of the booking process that produces the shipping label (waybill): confirmed means the label has been generated. The meaning of each value is documented on the ShippingBookingStatus enum reference; it is null until the booking process starts. In projects where the external warehouse validates the shippings, a shipping stays pending until the warehouse confirms its fulfilment. A shipping handed to a carrier that OMS does not book is unmanaged: its tracking is reported through the API.
The return shipping of a repayment request uses the same statuses: see Things to know about repayment requests.
Order line kinds
Every entry of Order.lines carries a kind (OrderLineKind) that tells what the line represents: read it before treating a line as a product. item lines are the products ordered; shipping_charge and payment_charge are the shipping and payment costs; coupon lines are order-level discounts. The meaning of each value is documented on the enum reference.
Discounts appear in two ways:
- Line-level discounts (a promotion or a coupon applied to a product) are already included in the line's
discountedUnitaryPrice, which is the final unit price of the line;originalUnitaryPricekeeps the full price, so the two differ exactly when a discount applies. - Order-level coupons are separate lines of kind
couponwith a negative price, in bothoriginalUnitaryPriceanddiscountedUnitaryPrice, that OMS subtracts from the order totals. They carry no goods: a warehouse skips them when preparing the shipment, and an accounting integration sums them with their sign.
The same rules apply to the lines submitted with Import an order.