Improve security and user management with our Authentication API.

Orders

Anatomy of an order

An order consists of several components, including a customer and line items. Merchants or users can manage orders from each market in an organization. In this section, you will learn about the structure of an order in Commerce Layer.

Anatomy of an order

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, discount(s) calculated from active promotions, redeemed gift card(s), a payment method, and a payment source type. The price of all components (those with prices) in an order is summed up. The cost of applied discounts and redeemed gift cards will be subtracted from the total amount. This will result in a new and final total. A customer will then checkout the order and pay the new total before shipping commences.

Those line items that have a frequency will be used to automatically generate the recurring orders involved in a subscription process (if any), triggered using a specific order's attribute.

Placing orders

The order placement process is by default synchronous. You can force your orders to be placed asynchronously by setting the related flag at the order level. Here is a list of steps (not necessarily an ordered sequence — some steps' order might change based on specific use cases) showing how an order works, from adding line items to the cart to order delivery.

  • A customer visits a sales channel (either as a registered or unregistered customer).
  • The customer selects the item(s) 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.
  • 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 in editing status to make some last changes (e.g. removing / changing items) as long as the order's total amount after the update is less than or equal to the authorized amount.
  • The order is approved and the customer's payment is captured.
  • All the 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 still not approved can be moved to the 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 that placed it on the condition that the changes don't lead to a total order amount that exceeds the previously authorized (or already captured, if that's the case) amount. As soon as the editing operations are finished, the order must be moved back to the placed status (again via trigger attribute, only by an integration application), from where it can then be approved.

The discounts due to the promotions applied at placement time are refreshed, new promotions (if any) due to the order editing are not applied. New coupons or gift cards can be applied, as long as not already present at the time of placement. If, after the order editing, the total amount 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 the editing status, you need to check again the available shipping methods (which may be different) and choose a new one to be re-associated with the edited 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 order validation is performed at the time of the order placement. If you need to execute custom validation (e.g. you want to support more complex validation rules specific to your business logic — such as market-specific quantities or SKUs) on some orders, you can leverage our external order validation feature.

Idempotency

Order status changes are idempotent. This means that the order and payment statuses stay consistent with multiple updates (e.g. it's possible to place or cancel an order more than once, without worrying about duplicated transactions and other unintended effects).