Anatomy of an order

What makes up an order and how it moves through placement, editing, and fulfillment

An order is a composite resource — from line items and addresses to payment and shipments — that moves through a well-defined lifecycle from draft to fulfilled.

Order structure

An order can consist of a customer, line items (SKUs, cost of shipping method, cost of payment method, taxes, or gift cards), a billing address, a shipping address, discounts calculated from active promotions, redeemed gift cards, a payment method, and a payment source type. The price of all components is summed up, and the cost of applied discounts and redeemed gift cards is subtracted from the total. The customer then checks out the order and pays the resulting total before shipping commences.

Line items that have a frequency are used to automatically generate recurring orders involved in a subscription process, triggered using a specific order attribute.

Placing orders

The order placement process is synchronous by default. You can force your orders to be placed asynchronously by setting the related flag at the order level.

The steps below illustrate a typical order flow from cart to delivery. The exact sequence may vary depending on the use case.

• A customer visits a sales channel (either as a registered or unregistered customer).

• The customer selects the items they want to purchase and adds them to the cart (including gift cards).

• The customer applies available discounts from active promotions (optional).

• The shopping cart is a draft order.

• Draft orders are labeled pending when the customer adds their email address.

• The customer enters their shipping and billing address.

• The customer selects a shipping and payment method defined for their market (a default one may already be set).

• The price of all items in the order is summed up.

• The customer makes the payment using their preferred payment source type.

• In case of asynchronous placement, the order is momentarily put in placing.

• The customer's payment is authorized and needs to be captured.

• The order can be cancelled before it is captured (cancelled orders will have their payment authorization voided).

• Before approval, placed orders can still be moved to editing status to make last-minute changes (e.g. removing or changing items), as long as the order total after the update does not exceed the authorized amount.

• The order is approved and the customer's payment is captured.

• All shipments generated by the approved order are shipped and the order fulfillment status becomes fulfilled.

Order editing

Draft and pending orders are always editable by a sales channel before placement. Once an order is placed but not yet approved, it can be moved to editing status by an integration application (for security reasons) via trigger attribute. When an order is in editing, it can be updated by the customer on the condition that the changes don't lead to a total that exceeds the previously authorized (or already captured) amount. Once editing is finished, the order must be moved back to placed status (again via trigger attribute, only by an integration application), from where it can then be approved.

Discounts from promotions applied at placement time are refreshed during editing. New promotions are not applied. New coupons or gift cards can be added, as long as they were not already present at the time of placement. If the total after editing is less than the authorized amount, the new amount will be captured. If the authorized amount was already captured, a partial refund will be performed. Shipments are rebuilt, so after any editing operation and before exiting editing status, you need to check the available shipping methods again and choose one to reassociate with the order.

Orders can be edited multiple times before approval. Once an editing operation is started, it can't be reverted but can be aborted by cancelling the order.

Order validation

Automatic validation is performed at the time of order placement. If you need to execute custom validation — for example, to support more complex business logic such as market-specific quantities or SKUs — you can leverage the external order validation feature.

Idempotency

Order status changes are idempotent. This means order and payment statuses stay consistent across multiple updates — for example, it's possible to place or cancel an order more than once without worrying about duplicated transactions or other unintended effects.