Introducing our brand new Rules Engine —
Read the docs
LogoLogo
Core APIOther APIsChangelog
API reference
API reference
  • Introduction
  • Addresses
    • The address object
    • Create an address
    • List all addresses
    • Retrieve an address
    • Update an address
    • Delete an address
  • Adjustments
    • The adjustment object
    • Create an adjustment
    • List all adjustments
    • Retrieve an adjustment
    • Update an adjustment
    • Delete an adjustment
  • Adyen gateways
    • The adyen gateway object
    • Create an adyen gateway
    • List all adyen gateways
    • Retrieve an adyen gateway
    • Update an adyen gateway
    • Delete an adyen gateway
  • Adyen payments
    • The adyen payment object
    • Create an adyen payment
    • List all adyen payments
    • Retrieve an adyen payment
    • Update an adyen payment
    • Delete an adyen payment
  • Applications
    • The application object
    • Retrieve the application
  • Attachments
    • The attachment object
    • Create an attachment
    • List all attachments
    • Retrieve an attachment
    • Update an attachment
    • Delete an attachment
  • Authorizations
    • The authorization object
    • List all authorizations
    • Retrieve an authorization
    • Update an authorization
  • Avalara accounts
    • The avalara account object
    • Create an avalara account
    • List all avalara accounts
    • Retrieve an avalara account
    • Update an avalara account
    • Delete an avalara account
  • Axerve gateways
    • The axerve gateway object
    • Create an axerve gateway
    • List all axerve gateways
    • Retrieve an axerve gateway
    • Update an axerve gateway
    • Delete an axerve gateway
  • Axerve payments
    • The axerve payment object
    • Create an axerve payment
    • List all axerve payments
    • Retrieve an axerve payment
    • Update an axerve payment
    • Delete an axerve payment
  • Bing geocoders
    • The bing geocoder object
    • Create a bing geocoder
    • List all bing geocoders
    • Retrieve a bing geocoder
    • Update a bing geocoder
    • Delete a bing geocoder
  • Braintree gateways
    • The braintree gateway object
    • Create a braintree gateway
    • List all braintree gateways
    • Retrieve a braintree gateway
    • Update a braintree gateway
    • Delete a braintree gateway
  • Braintree payments
    • The braintree payment object
    • Create a braintree payment
    • List all braintree payments
    • Retrieve a braintree payment
    • Update a braintree payment
    • Delete a braintree payment
  • Bundles
    • The bundle object
    • Create a bundle
    • List all bundles
    • Retrieve a bundle
    • Update a bundle
    • Delete a bundle
  • Buy x pay y promotions
    • The buy x pay y promotion object
    • Create a buy x pay y promotion
    • List all buy x pay y promotions
    • Retrieve a buy x pay y promotion
    • Update a buy x pay y promotion
    • Delete a buy x pay y promotion
  • Captures
    • The capture object
    • List all captures
    • Retrieve a capture
    • Update a capture
  • Carrier accounts
    • The carrier account object
    • Create a carrier account
    • List all carrier accounts
    • Retrieve a carrier account
    • Update a carrier account
    • Delete a carrier account
  • Checkout.com gateways
    • The checkout.com gateway object
    • Create a checkout.com gateway
    • List all checkout.com gateways
    • Retrieve a checkout.com gateway
    • Update a checkout.com gateway
    • Delete a checkout.com gateway
  • Checkout.com payments
    • The checkout.com payment object
    • Create a checkout.com payment
    • List all checkout.com payments
    • Retrieve a checkout.com payment
    • Update a checkout.com payment
    • Delete a checkout.com payment
  • Cleanups
    • The cleanup object
    • Create a cleanup
    • List all cleanups
    • Retrieve a cleanup
    • Update a cleanup
    • Delete a cleanup
  • Coupon codes promotion rules
    • The coupon codes promotion rule object
    • Create a coupon codes promotion rule
    • List all coupon codes promotion rules
    • Retrieve a coupon codes promotion rule
    • Update a coupon codes promotion rule
    • Delete a coupon codes promotion rule
  • Coupon recipients
    • The coupon recipient object
    • Create a coupon recipient
    • List all coupon recipients
    • Retrieve a coupon recipient
    • Update a coupon recipient
    • Delete a coupon recipient
  • Coupons
    • The coupon object
    • Create a coupon
    • List all coupons
    • Retrieve a coupon
    • Update a coupon
    • Delete a coupon
  • Custom promotion rules
    • The custom promotion rule object
    • Create a custom promotion rule
    • List all custom promotion rules
    • Retrieve a custom promotion rule
    • Update a custom promotion rule
    • Delete a custom promotion rule
  • Customer addresses
    • The customer address object
    • Create a customer address
    • List all customer addresses
    • Retrieve a customer address
    • Update a customer address
    • Delete a customer address
  • Customer groups
    • The customer group object
    • Create a customer group
    • List all customer groups
    • Retrieve a customer group
    • Update a customer group
    • Delete a customer group
  • Customer password resets
    • The customer password reset object
    • Create a customer password reset
    • List all customer password resets
    • Retrieve a customer password reset
    • Update a customer password reset
    • Delete a customer password reset
  • Customer payment sources
    • The customer payment source object
    • Create a customer payment source
    • List all customer payment sources
    • Retrieve a customer payment source
    • Update a customer payment source
    • Delete a customer payment source
  • Customer subscriptions
    • The customer subscription object
    • Create a customer subscription
    • List all customer subscriptions
    • Retrieve a customer subscription
    • Update a customer subscription
    • Delete a customer subscription
  • Customers
    • The customer object
    • Create a customer
    • List all customers
    • Retrieve a customer
    • Update a customer
    • Delete a customer
  • Delivery lead times
    • The delivery lead time object
    • Create a delivery lead time
    • List all delivery lead times
    • Retrieve a delivery lead time
    • Update a delivery lead time
    • Delete a delivery lead time
  • Easypost pickups
    • The easypost pickup object
    • Create an easypost pickup
    • List all easypost pickups
    • Retrieve an easypost pickup
    • Update an easypost pickup
    • Delete an easypost pickup
  • Event callbacks
    • The event callback object
    • List all event callbacks
    • Retrieve an event callback
  • Events
    • The event object
    • List all events
    • Retrieve an event
    • Update an event
  • Exports
    • The export object
    • Create an export
    • List all exports
    • Retrieve an export
    • Update an export
    • Delete an export
  • External gateways
    • The external gateway object
    • Create an external gateway
    • List all external gateways
    • Retrieve an external gateway
    • Update an external gateway
    • Delete an external gateway
  • External payments
    • The external payment object
    • Create an external payment
    • List all external payments
    • Retrieve an external payment
    • Update an external payment
    • Delete an external payment
  • External promotions
    • The external promotion object
    • Create an external promotion
    • List all external promotions
    • Retrieve an external promotion
    • Update an external promotion
    • Delete an external promotion
  • External tax calculators
    • The external tax calculator object
    • Create an external tax calculator
    • List all external tax calculators
    • Retrieve an external tax calculator
    • Update an external tax calculator
    • Delete an external tax calculator
  • Fixed amount promotions
    • The fixed amount promotion object
    • Create a fixed amount promotion
    • List all fixed amount promotions
    • Retrieve a fixed amount promotion
    • Update a fixed amount promotion
    • Delete a fixed amount promotion
  • Fixed price promotions
    • The fixed price promotion object
    • Create a fixed price promotion
    • List all fixed price promotions
    • Retrieve a fixed price promotion
    • Update a fixed price promotion
    • Delete a fixed price promotion
  • Flex promotions
    • The flex promotion object
    • Create a flex promotion
    • List all flex promotions
    • Retrieve a flex promotion
    • Update a flex promotion
    • Delete a flex promotion
  • Free gift promotions
    • The free gift promotion object
    • Create a free gift promotion
    • List all free gift promotions
    • Retrieve a free gift promotion
    • Update a free gift promotion
    • Delete a free gift promotion
  • Free shipping promotions
    • The free shipping promotion object
    • Create a free shipping promotion
    • List all free shipping promotions
    • Retrieve a free shipping promotion
    • Update a free shipping promotion
    • Delete a free shipping promotion
  • Geocoders
    • The geocoder object
    • List all geocoders
    • Retrieve a geocoder
  • Gift card recipients
    • The gift card recipient object
    • Create a gift card recipient
    • List all gift card recipients
    • Retrieve a gift card recipient
    • Update a gift card recipient
    • Delete a gift card recipient
  • Gift cards
    • The gift card object
    • Create a gift card
    • List all gift cards
    • Retrieve a gift card
    • Update a gift card
    • Delete a gift card
  • Google geocoders
    • The google geocoder object
    • Create a google geocoder
    • List all google geocoders
    • Retrieve a google geocoder
    • Update a google geocoder
    • Delete a google geocoder
  • Imports
    • The import object
    • Create an import
    • List all imports
    • Retrieve an import
    • Update an import
    • Delete an import
  • In stock subscriptions
    • The in stock subscription object
    • Create an in stock subscription
    • List all in stock subscriptions
    • Retrieve an in stock subscription
    • Update an in stock subscription
    • Delete an in stock subscription
  • Inventory models
    • The inventory model object
    • Create an inventory model
    • List all inventory models
    • Retrieve an inventory model
    • Update an inventory model
    • Delete an inventory model
  • Inventory return locations
    • The inventory return location object
    • Create an inventory return location
    • List all inventory return locations
    • Retrieve an inventory return location
    • Update an inventory return location
    • Delete an inventory return location
  • Inventory stock locations
    • The inventory stock location object
    • Create an inventory stock location
    • List all inventory stock locations
    • Retrieve an inventory stock location
    • Update an inventory stock location
    • Delete an inventory stock location
  • Klarna gateways
    • The klarna gateway object
    • Create a klarna gateway
    • List all klarna gateways
    • Retrieve a klarna gateway
    • Update a klarna gateway
    • Delete a klarna gateway
  • Klarna payments
    • The klarna payment object
    • Create a klarna payment
    • List all klarna payments
    • Retrieve a klarna payment
    • Update a klarna payment
    • Delete a klarna payment
  • Line item options
    • The line item option object
    • Create a line item option
    • List all line item options
    • Retrieve a line item option
    • Update a line item option
    • Delete a line item option
  • Line items
    • The line item object
    • Create a line item
    • List all line items
    • Retrieve a line item
    • Update a line item
    • Delete a line item
  • Links
    • The link object
    • Create a link
    • List all links
    • Retrieve a link
    • Update a link
    • Delete a link
  • Manual gateways
    • The manual gateway object
    • Create a manual gateway
    • List all manual gateways
    • Retrieve a manual gateway
    • Update a manual gateway
    • Delete a manual gateway
  • Manual tax calculators
    • The manual tax calculator object
    • Create a manual tax calculator
    • List all manual tax calculators
    • Retrieve a manual tax calculator
    • Update a manual tax calculator
    • Delete a manual tax calculator
  • Markets
    • The market object
    • Create a market
    • List all markets
    • Retrieve a market
    • Update a market
    • Delete a market
  • Merchants
    • The merchant object
    • Create a merchant
    • List all merchants
    • Retrieve a merchant
    • Update a merchant
    • Delete a merchant
  • Notifications
    • The notification object
    • Create a notification
    • List all notifications
    • Retrieve a notification
    • Update a notification
    • Delete a notification
  • Order amount promotion rules
    • The order amount promotion rule object
    • Create an order amount promotion rule
    • List all order amount promotion rules
    • Retrieve an order amount promotion rule
    • Update an order amount promotion rule
    • Delete an order amount promotion rule
  • Order copies
    • The order copy object
    • Create an order copy
    • List all order copies
    • Retrieve an order copy
    • Update an order copy
    • Delete an order copy
  • Order factories
    • The order factory object
    • List all order factories
    • Retrieve an order factory
  • Order subscription items
    • The order subscription item object
    • Create an order subscription item
    • List all order subscription items
    • Retrieve an order subscription item
    • Update an order subscription item
    • Delete an order subscription item
  • Order subscriptions
    • The order subscription object
    • Create an order subscription
    • List all order subscriptions
    • Retrieve an order subscription
    • Update an order subscription
    • Delete an order subscription
  • Orders
    • The order object
    • Create an order
    • List all orders
    • Retrieve an order
    • Update an order
    • Delete an order
  • Organizations
    • The organization object
    • Retrieve the organization
  • Packages
    • The package object
    • Create a package
    • List all packages
    • Retrieve a package
    • Update a package
    • Delete a package
  • Parcel line items
    • The parcel line item object
    • Create a parcel line item
    • List all parcel line items
    • Retrieve a parcel line item
    • Update a parcel line item
    • Delete a parcel line item
  • Parcels
    • The parcel object
    • Create a parcel
    • List all parcels
    • Retrieve a parcel
    • Update a parcel
    • Delete a parcel
  • Payment gateways
    • The payment gateway object
    • List all payment gateways
    • Retrieve a payment gateway
  • Payment methods
    • The payment method object
    • Create a payment method
    • List all payment methods
    • Retrieve a payment method
    • Update a payment method
    • Delete a payment method
  • Payment options
    • The payment option object
    • Create a payment option
    • List all payment options
    • Retrieve a payment option
    • Update a payment option
    • Delete a payment option
  • Paypal gateways
    • The paypal gateway object
    • Create a paypal gateway
    • List all paypal gateways
    • Retrieve a paypal gateway
    • Update a paypal gateway
    • Delete a paypal gateway
  • Paypal payments
    • The paypal payment object
    • Create a paypal payment
    • List all paypal payments
    • Retrieve a paypal payment
    • Update a paypal payment
    • Delete a paypal payment
  • Percentage discount promotions
    • The percentage discount promotion object
    • Create a percentage discount promotion
    • List all percentage discount promotions
    • Retrieve a percentage discount promotion
    • Update a percentage discount promotion
    • Delete a percentage discount promotion
  • Pickups
    • The pickup object
    • List all pickups
    • Retrieve a pickup
  • Price frequency tiers
    • The price frequency tier object
    • Create a price frequency tier
    • List all price frequency tiers
    • Retrieve a price frequency tier
    • Update a price frequency tier
    • Delete a price frequency tier
  • Price list schedulers
    • The price list scheduler object
    • Create a price list scheduler
    • List all price list schedulers
    • Retrieve a price list scheduler
    • Update a price list scheduler
    • Delete a price list scheduler
  • Price lists
    • The price list object
    • Create a price list
    • List all price lists
    • Retrieve a price list
    • Update a price list
    • Delete a price list
  • Price tiers
    • The price tier object
    • List all price tiers
    • Retrieve a price tier
  • Price volume tiers
    • The price volume tier object
    • Create a price volume tier
    • List all price volume tiers
    • Retrieve a price volume tier
    • Update a price volume tier
    • Delete a price volume tier
  • Prices
    • The price object
    • Create a price
    • List all prices
    • Retrieve a price
    • Update a price
    • Delete a price
  • Promotion rules
    • The promotion rule object
    • List all promotion rules
    • Retrieve a promotion rule
  • Promotions
    • The promotion object
    • List all promotions
    • Retrieve a promotion
  • Recurring order copies
    • The recurring order copy object
    • Create a recurring order copy
    • List all recurring order copies
    • Retrieve a recurring order copy
    • Update a recurring order copy
    • Delete a recurring order copy
  • Refunds
    • The refund object
    • List all refunds
    • Retrieve a refund
    • Update a refund
  • Reserved stocks
    • The reserved stock object
    • List all reserved stocks
    • Retrieve a reserved stock
  • Resource errors
    • The resource error object
    • List all resource errors
    • Retrieve a resource error
  • Return line items
    • The return line item object
    • Create a return line item
    • List all return line items
    • Retrieve a return line item
    • Update a return line item
    • Delete a return line item
  • Returns
    • The return object
    • Create a return
    • List all returns
    • Retrieve a return
    • Update a return
    • Delete a return
  • Satispay gateways
    • The satispay gateway object
    • Create a satispay gateway
    • List all satispay gateways
    • Retrieve a satispay gateway
    • Update a satispay gateway
    • Delete a satispay gateway
  • Satispay payments
    • The satispay payment object
    • Create a satispay payment
    • List all satispay payments
    • Retrieve a satispay payment
    • Update a satispay payment
    • Delete a satispay payment
  • Shipments
    • The shipment object
    • Create a shipment
    • List all shipments
    • Retrieve a shipment
    • Update a shipment
    • Delete a shipment
  • Shipping categories
    • The shipping category object
    • Create a shipping category
    • List all shipping categories
    • Retrieve a shipping category
    • Update a shipping category
    • Delete a shipping category
  • Shipping method tiers
    • The shipping method tier object
    • List all shipping method tiers
    • Retrieve a shipping method tier
  • Shipping methods
    • The shipping method object
    • Create a shipping method
    • List all shipping methods
    • Retrieve a shipping method
    • Update a shipping method
    • Delete a shipping method
  • Shipping weight tiers
    • The shipping weight tier object
    • Create a shipping weight tier
    • List all shipping weight tiers
    • Retrieve a shipping weight tier
    • Update a shipping weight tier
    • Delete a shipping weight tier
  • Shipping zones
    • The shipping zone object
    • Create a shipping zone
    • List all shipping zones
    • Retrieve a shipping zone
    • Update a shipping zone
    • Delete a shipping zone
  • SKU list items
    • The SKU list item object
    • Create a SKU list item
    • List all SKU list items
    • Retrieve a SKU list item
    • Update a SKU list item
    • Delete a SKU list item
  • SKU list promotion rules
    • The SKU list promotion rule object
    • Create a SKU list promotion rule
    • List all SKU list promotion rules
    • Retrieve a SKU list promotion rule
    • Update a SKU list promotion rule
    • Delete a SKU list promotion rule
  • SKU lists
    • The SKU list object
    • Create a SKU list
    • List all SKU lists
    • Retrieve a SKU list
    • Update a SKU list
    • Delete a SKU list
  • SKU options
    • The SKU option object
    • Create a SKU option
    • List all SKU options
    • Retrieve a SKU option
    • Update a SKU option
    • Delete a SKU option
  • SKUs
    • The SKU object
    • Create a SKU
    • List all SKUs
    • Retrieve a SKU
    • Update a SKU
    • Delete a SKU
  • Stock items
    • The stock item object
    • Create a stock item
    • List all stock items
    • Retrieve a stock item
    • Update a stock item
    • Delete a stock item
  • Stock line items
    • The stock line item object
    • Create a stock line item
    • List all stock line items
    • Retrieve a stock line item
    • Update a stock line item
    • Delete a stock line item
  • Stock locations
    • The stock location object
    • Create a stock location
    • List all stock locations
    • Retrieve a stock location
    • Update a stock location
    • Delete a stock location
  • Stock reservations
    • The stock reservation object
    • Create a stock reservation
    • List all stock reservations
    • Retrieve a stock reservation
    • Update a stock reservation
    • Delete a stock reservation
  • Stock transfers
    • The stock transfer object
    • Create a stock transfer
    • List all stock transfers
    • Retrieve a stock transfer
    • Update a stock transfer
    • Delete a stock transfer
  • Stores
    • The store object
    • Create a store
    • List all stores
    • Retrieve a store
    • Update a store
    • Delete a store
  • Stripe gateways
    • The stripe gateway object
    • Create a stripe gateway
    • List all stripe gateways
    • Retrieve a stripe gateway
    • Update a stripe gateway
    • Delete a stripe gateway
  • Stripe payments
    • The stripe payment object
    • Create a stripe payment
    • List all stripe payments
    • Retrieve a stripe payment
    • Update a stripe payment
    • Delete a stripe payment
  • Stripe tax accounts
    • The stripe tax account object
    • Create a stripe tax account
    • List all stripe tax accounts
    • Retrieve a stripe tax account
    • Update a stripe tax account
    • Delete a stripe tax account
  • Subscription models
    • The subscription model object
    • Create a subscription model
    • List all subscription models
    • Retrieve a subscription model
    • Update a subscription model
    • Delete a subscription model
  • Tags
    • The tag object
    • Create a tag
    • List all tags
    • Retrieve a tag
    • Update a tag
    • Delete a tag
  • Tax calculators
    • The tax calculator object
    • List all tax calculators
    • Retrieve a tax calculator
  • Tax categories
    • The tax category object
    • Create a tax category
    • List all tax categories
    • Retrieve a tax category
    • Update a tax category
    • Delete a tax category
  • Tax rules
    • The tax rule object
    • Create a tax rule
    • List all tax rules
    • Retrieve a tax rule
    • Update a tax rule
    • Delete a tax rule
  • Taxjar accounts
    • The taxjar account object
    • Create a taxjar account
    • List all taxjar accounts
    • Retrieve a taxjar account
    • Update a taxjar account
    • Delete a taxjar account
  • Transactions
    • The transaction object
    • List all transactions
    • Retrieve a transaction
  • Versions
    • The version object
    • List all versions
    • Retrieve a version
  • Vertex accounts
    • The vertex account object
    • Create a vertex account
    • List all vertex accounts
    • Retrieve a vertex account
    • Update a vertex account
    • Delete a vertex account
  • Voids
    • The void object
    • List all voids
    • Retrieve a void
    • Update a void
  • Webhooks
    • The webhook object
    • Create a webhook
    • List all webhooks
    • Retrieve a webhook
    • Update a webhook
    • Delete a webhook
  • Wire transfers
    • The wire transfer object
    • Create a wire transfer
    • List all wire transfers
    • Retrieve a wire transfer
    • Update a wire transfer
    • Delete a wire transfer
On this page
  • Asynchronous order placement
  • Auto-refresh
  • Order editing
  • Promotions, coupons, and gift cards
  • Shipments and shipping methods
  • Non-editable attributes
  • Default payment method
  • Changing the order number
  • Stock reservation
  • Capture options
  • Automatic subscriptions generation
  • Order validation
  • Order errors
  • Taxable items
  • Payment options
  • Idempotency

Orders

The order object and the allowed CRUD operations on the related resource endpoint

PreviousDelete an order subscriptionNextThe order object

Last updated 10 days ago

Orders get created in draft status and become pending when they have a customer and some line items.

Draft orders act as shopping carts — see our on how to manage shopping carts. Draft orders that aren't associated with a customer are automatically deleted after 2 months since the latest update.

For performance reasons (and to make sure no to hit the API ), 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 or cancelled when abandoned. The status of an order is closely linked to the related payment and fulfillment statuses. Orders are placed synchronously by default, if you need to place them asychronously and transit through the placing status use the place_async attribute. When an order is placed, it can either get approved or cancelled.

Placed orders cannot be deleted. To archive them you can patch them passing the _archive trigger attribute. You can them using the query filter[q][archived_at_null]=false, for them using the Metrics API, or see them in the related section of the Dashboard Orders app.

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

Empty order creation

draft

unpaid

unfulfilled

Association with a customer and addition of a purchasable item

pending

unpaid

unfulfilled

Async order placement with errors

placing

unpaid

unfulfilled

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.

The table above describes the most common order's lifecycle scenario. Some specific use cases (e.g. the ones involving manual actions on orders and shipments) might slightly differ.

Data model

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.

Asynchronous order placement

To place an order asynchronously, you just need to set the place_async flag to true (default is false). In this scenario, only a subset of the standard synchronous validations (needed to check the order integrity) is performed when passing the _place trigger attribute:

  • Customer — the correct association with an existing customer is checked.

  • Billing — the correct association with an existing billing address is checked.

  • Items — the presence of at least one SKU, bundle, positive gift card (i.e. purchasing a gift card), or positive adjustment is checked.

  • Shipping — the correct association with an existing shipping method and shipping address is checked.

  • Payment — the correct association with an existing payment method and payment source is checked.

If some errors occur at this stage, the order stays pending and cannot be placed. If those validations are successful, the order is moved to an intermediate status (placing) where the remaining validations are added:

  • Coupons — the validity of the associated coupon code (if any) is checked.

  • Stock — the availability of the necessary stock to fulfill the order is checked.

  • Authorization — the selected payment gateway is called to get the payment authorized.

If also those validations are successful and no errors come from the gateway, the order is safely placed and moved through the next steps of its lifecycle. If some of the additional validations throw an error you need to fix it (e.g. adding the missing stock) and manually re-trigger the _place (which will be again performed asynchronously unless the place_async flag is not set back to false).

Since 3D Secure (3DS) payments require real-time user interaction during the authorization process, they cannot be supported when choosing an asynchronous order placement flow.

Auto-refresh

By default, orders that are still editable (i.e. in draft or pending status) are automatically refreshed each time they get updated and/or one of the related line items gets created, updated, or destroyed. This automatically triggers several actions:

  • Any active promotions and/or gift cards are applied and the related discounts are recalculated.

  • Any negative adjustment is redistributed on the taxable items.

  • If the market associated with the order has a tax calculator, taxes get updated.

  • All of the internal amounts and counters are refreshed.

To better handle these specific scenarios you can leverage the order's autorefresh attribute and set it to false (default is true) to prevent the automatic triggering of the above-mentioned actions. This choice will result in stale order data, but will ensure a much faster order editing (the performance gain will build up exponentially with increasing number of line items — we estimate an average boost of 500%). Once the editing is completed, the attribute can be updated back to true, which automatically triggers a new refresh of the order (in any case, remember that there is always the option to force a refresh manually even when the order auto-refresh is disabled by passing the _refresh trigger attribute).

If your top priority is pure performance and you're fine with getting a refreshed snapshot of the order just before placing it rather than in real time, we strongly recommend disabling the order auto-refresh option when needed.

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 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.

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.

Promotions, coupons, and gift cards

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 and shipping methods

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.

Non-editable attributes

  • market

  • customer

  • shipping_address

  • payment_method

  • payment_source

  • gift_card_code

  • coupon_code

You can still edit the attributes above if the order is in the placed status by entering order editing, otherwise they are considered frozen and not editable anymore.

Altering the non-editable attributes during the order's placement process is not permitted, since they can trigger collateral effects after the order has been placed (e.g. promotions application, shipments rebuild, etc.) and cause an inconsistent order status. If you patch the order passing the _place trigger attribute together with some attribute or relationship that would alter any of the non-editable ones, no error is raised (to guarantee the order's placement), but the changes are silently ignored.

Default payment method

  • Existing orders with no payment method associated will not be automatically associated with the default one until a new validation on the order is triggered (e.g. order editing).

In any case, the associated line item of type payment_methods will be created/recreated accordingly and the default payment method will be listed in the available_payment_methods array associated with the order.

Changing the order number

The default order numeric identifier can be changed according to your needs as long as the passed value is unique within the specific organization environment.

Stock reservation

Capture options

Automatic subscriptions generation

Order validation

How-to

Order errors

The latest 10 errors occurring during the attempt to place an order (both synchronously and asynchronously), including the ones coming from external validations or subscription processes, are stored in the related resource errors array until order approval. To inspect them, you just need to fetch the error including the resource errors association. You can also leverage the errors_count attribute (which is reset to 0 once the order is approved) at the order level.

Taxable items

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_taxable to true if you want to add the line items of type shipments (i.e. shipping costs) to the taxable items list.

  • Set payment_method_taxable to true if you want to add the line items of type payment_methods (i.e. specific payment method costs) to the taxable items list.

  • Set adjustment_taxable to true if you want to add the line items of type adjustments (i.e. positive adjustments) to the taxable items list.

  • Set gift_card_taxable to true if you want to add the line items of type gift_cards (i.e. purchased gift cards) to the taxable items list.

Payment options

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.

Idempotency

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.

External validation — if any (i.e. if and external_order_validation_url is set at the level).

The orders that are in placing status can be fetched but not edited by a sales channel. To patch them you need to use API credentials. If you need the customer to fix the error that's keeping the order in placing you can pass the _pending trigger attribute and move it back to the pending status.

If the order is already associated with a shipping address, the related shipments are rebuilt based on the related .

All of the above gets calculated in sequence for each of the order's line items, resulting in a pretty intensive computation, which can considerably slow down in case one or more are involved. This may lead to concurrent request issues and/or timeout errors, making the automatic refresh not ideal, especially when you have to deal with cart containing a large number of line items (e.g. B2B).

For security reasons, only 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.

Shipments are rebuilt so, after any editing operation and before exiting the editing status, you need to check again the (which may be different) and choose a new one to be with the edited order, otherwise the API will return an error on the _stop_editing.

can edit almost every order attribute or relationship even if the order is in a non-editable status (i.e. a different one from draft, pending, or editing — see for more information), with a few exceptions, listed below. If the order is no longer editable, the following attributes and relationships cannot be edited using any API credentials:

If you set a for a market, all the market's orders not already associated with a payment method will be automatically associated with the default one. Specifically:

If you create a new order, it will be automatically associated with the default payment method at creation time. Then, if needed, you can change the payment method by patching the order and .

If an order is already associated with a payment method and the association is , the order will be automatically associated with the default payment method.

This feature is available for enterprise plans only and can be activated by (meaning you can request to enable it in test mode, in live mode or both — inspect the related organization's flags order_number_editable_test and order_number_editable_live to check your configuration).

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 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 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 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 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 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.

Check the related to learn how to validate orders via external services.

integration
external resources
integrations
Integrations
Roles and permissions
updating the relationship
removed
environment
external order validation
guide
market
default payment method
delayed capture
trigger attribute
rate limits
filter
search
how-to
inventory model's strategy
available shipping methods
re-associated
auto-capture
trigger the automatic order subscription generation