Skip to main content

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: number is the identifier assigned by the integration that submitted the order, deliveryId the one the customer sees in the e-shop (in almost all cases the same value); channel is the sales channel the order belongs to.
  • status: where the order is in its lifecycle, see Order statuses below.
  • lines: what was bought, one OrderLine per product, cost or discount, with kind, 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, one Shipping each; 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), the warehouse it ships from, the item quantities it dispatches (itemLines), its parcels and its documents: the shipping labels (waybills: one per parcel or a single one for all the parcels, depending on the carrier) and the proforma.
  • Totals: totalNetAmount, totalVatAmount and totalGrossAmount are computed by OMS from the lines; totalPaidAmount is what the customer actually paid, as submitted at import.
  • Documents: accountingDocuments are the fiscal documents issued for the order (receipt, invoice), fiscalDocument the latest of them, see Get order documents.
  • Related records: saleTransactions are the payment transactions linked to the order (see Payments), repaymentRequests its returns (see Repayments).
  • Dates: createdAt is when the order was placed on the channel, receivedAt when OMS received it, paidAt and cancelledAt when 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_anomalies is 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 only status changed.
  • cancelled and refunded are the two ways an order ends without being processed. Both are reached from with_anomalies and differ only by whether a payment had been received and refunded: in both cases the goods are never shipped.
  • A completed order 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: read Order.repaymentRequests to 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.
note

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; originalUnitaryPrice keeps the full price, so the two differ exactly when a discount applies.
  • Order-level coupons are separate lines of kind coupon with a negative price, in both originalUnitaryPrice and discountedUnitaryPrice, 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.