Orders
The order object and the allowed CRUD operations on the related resource endpoint
Orders get created in
draft status and become pending when they have a customer and some line items.For performance reasons (and to make sure no to hit the API rate limits), we we strongly advise against dealing with empty carts — just create a new order right before adding the first line item to it.
pending orders can be recovered when abandoned. The status of an order is closely linked to the related payment and fulfillment statuses. When an order is placed, it can either get approved or cancelled. An approved order becomes fulfilled when paid and shipped. Cancelling an order automatically voids its payment source's authorization. Captured payments can be refunded, either fully or partially.Action | Order status | Payment status | Fulfillment status |
|---|---|---|---|
Order placement | placed | authorized | unfulfilled |
Order editing | editing | authorized | unfulfilled |
Order cancellation | cancelled | voided | unfulfilled |
Order approval | approved | authorized | unfulfilled |
Payment capture | approved | paid | in_progress |
Refund (partial) | approved | partially_refunded | No changes to the previous fulfillment status. |
Refund (full) | cancelled | refunded | unfulfilled if in progress, otherwise fulfilled. |
All shipments shipped | approved | paid | fulfilled |
The payment status of the orders that have a total amount equal to zero is automatically set to
free. If the order contains items flagged as do_not_ship only, its fulfillment status is automatically not_required.Read more about the anatomy of an order here and check the related ER diagram that illustrates how the order resource relates to the other API entities.
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 passing the _start_editing trigger attribute. As soon as the editing operations are finished, the order must be moved back to the placed status by passing the _stop_editing trigger attribute.For security reasons, only integration applications are allowed to change the
_start_editing and _stop_editing attributes of an order. When an order is in the editing status it can be updated by the customer that placed it.When an order is in editing you can make almost any change you need (e.g. adding or removing line items, coupon or gift cards, adjustment, etc.) except replace the payment source and payment method, on the condition that the updates don't lead to a total order amount that exceeds the previously authorized (or already captured, if that's the case) amount, otherwise the API will return an error on the
_stop_editing. 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 and no further edit to the order will be allowed.The discounts due to the active promotions applied at placement time are refreshed according to the changes applied to the order, even if the promotions should have expired in the meanwhile. New promotions (if any) triggered by the changes due to the order editing are not applied. Coupons and/or gift cards applied at placement time are still valid (even single-use ones). New coupons or gift cards can be applied, as long as one of them wasn't already present at the time of placement.
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, otherwise the API will return an error on the
_stop_editing.Orders can be edited multiple times before approval. Please note that once an editing operation is started, it can't be reverted. It can always be aborted by cancelling the order.
When an order is placed the stock reservations needed to block the whole order's stock are automatically created and the associated stock is reserved without decrementing the stock item quantities. Once the order is approved the stock item quantities are decremented. If the order is cancelled the reserved stock is released becoming available again. You can temporarily reserve the stock associated with a line item before the order placement by sending a specific trigger attribute when adding the line item to the order.
By default, payments are required to be captured before being able to start fulfilling the related orders. You can override this constraint by allowing a delayed capture at the payment method level. This way, the fulfillment status can become
in_progress even if the payment status is not paid yet.Similarly, you can decide to unify the authorization and capture steps and automatically capture payments upon authorization by enabling the auto-capture option. This way if the authorization succeeds, a successful capture is automatically generated and the order's payment status is set to
paid.If a subscription model is associated with the same market as an order, subscriptions can be automatically generated for all the line items that have a frequency, based on the strategy set at the subscription model level. To trigger the automatic order subscription generation you just need to update the source order after placement and pass the
_create_subscriptions attribute.Automatic order validation is performed at the time of the order placement. Sometimes, you may need to implement custom validation (e.g. you want to support more complex validation rules specific to your business logic) on some orders, as an additional step before the order placement. To do that, you can leverage Commerce Layer's external order validation feature — just make sure to correctly set up the URL of your external service (that will be in charge of computing the validation logic) at the market level and update the order(s) in question by setting the
_validate trigger attribute to true.The taxable items of an order are used for tax and discount distributions. Line items of type
skus and bundles are taxable by default. As for the other item types, you need to set this property by specifying the related attribute at the order level:- Set
freight_taxabletotrueif you want to add the line items of typeshipments(i.e. shipping costs) to the taxable items list. - Set
payment_method_taxabletotrueif you want to add the line items of typepayment_methods(i.e. specific payment method costs) to the taxable items list. - Set
adjustment_taxabletotrueif you want to add the line items of typeadjustments(i.e. positive adjustments) to the taxable items list. - Set
gift_card_taxabletotrueif you want to add the line items of typegift_cards(i.e. purchased gift cards) to the taxable items list.
You can associate additional payment options with an order to extend the information we send to the payment gateway at the moment of the payment creation (e.g. to leverage Stripe Connect and accept payments on behalf of connected accounts). Make sure to do it before the payment source creation so that they can be properly injected.
Order status changes are idempotent. The order and payment statuses are granted to be consistent upon multiple updates (e.g. it's possible to place or cancel an order multiple times, without worrying about duplicated transactions and other side effects).
This can be useful to force a payment status (e.g.
paid), in case the payment gateway has recorded the capture, but for some reason (typically the gateway's timeout) the order kept an inconsistent payment status (e.g. authorized). Webhooks's events, stock item updates, and other status-related actions are granted to be executed only once.Last modified 21d ago