The order object and the allowed CRUD operations on the related resource endpoint
Orders get created in
draftstatus and become
pendingwhen they have a customer and some line items.
pendingorders can be recovered when abandoned. The status of an order is strictly dependent on the related payment and fulfillment statuses. When an order is
placed, it can either get
cancelled. An approved order becomes
fulfilledwhen paid and shipped. Cancelling an order automatically voids its payment source's authorization. Captured payments can be refunded, either fully or partially.
No changes to the previous fulfillment status.
All shipments shipped
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_shiponly, its fulfillment status is automatically
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.
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_progresseven if the payment status is not
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
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 pass the
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
_validatetrigger attribute to
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.