The order object

A comprehensive list of the order resource's attributes and relationships

An order object is returned as part of the response body of each successful list, retrieve, create or update API call to the /api/orders endpoint.

Fields

Field
Type
Description

type

string

orders

id

string

The order unique identifier

links.self

string

The order endpoint URL

attributes.number

string

The order identifier. Can be specified if unique within the organization (for enterprise plans only), default to numeric ID otherwise. Cannot be passed by sales channels.

attributes.affiliate_code

string

The affiliate code, if any, to track commissions using any third party services.

attributes.autorefresh

boolean

Save this attribute as 'false' if you want prevent the order to be refreshed automatically at each change (much faster).

attributes.place_async

boolean

Save this attribute as 'true' if you want perform the place asynchronously. Payment errors, if any, will be collected afterwards.

attributes.status

string

The order status. One of 'draft' (default), 'pending', 'editing', 'placing', 'placed', 'approved', or 'cancelled'.

attributes.payment_status

string

The order payment status. One of 'unpaid' (default), 'authorized', 'partially_authorized', 'paid', 'partially_paid', 'voided', 'partially_voided', 'refunded', 'partially_refunded', or 'free'.

attributes.fulfillment_status

string

The order fulfillment status. One of 'unfulfilled' (default), 'in_progress', 'fulfilled', or 'not_required'.

attributes.guest

boolean

Indicates if the order has been placed as guest.

attributes.editable

boolean

Indicates if the order can be edited.

attributes.customer_email

string

The email address of the associated customer. When creating or updating an order, this is a shortcut to find or create the associated customer by email.

attributes.customer_password

string

The password of the associated customer. When creating or updating an order, this is a shortcut to sign up the associated customer.

attributes.language_code

string

The preferred language code (ISO 639-1) to be used when communicating with the customer. This can be useful when sending the order to 3rd party marketing tools and CRMs. If the language is supported, the hosted checkout will be localized accordingly.

attributes.currency_code

string

The international 3-letter currency code as defined by the ISO 4217 standard, automatically inherited from the order's market.

attributes.tax_included

boolean

Indicates if taxes are included in the order amounts, automatically inherited from the order's price list.

attributes.tax_rate

float

The tax rate for this order (if calculated).

attributes.freight_taxable

boolean

Indicates if taxes are applied to shipping costs.

attributes.payment_method_taxable

boolean

Indicates if taxes are applied to payment methods costs.

attributes.adjustment_taxable

boolean

Indicates if taxes are applied to positive adjustments.

attributes.gift_card_taxable

boolean

Indicates if taxes are applied to purchased gift cards.

attributes.requires_billing_info

boolean

Indicates if the billing address associated to this order requires billing info to be present.

attributes.country_code

string

The international 2-letter country code as defined by the ISO 3166-1 standard, automatically inherited from the order's shipping or billing addresses.

attributes.shipping_country_code_lock

string

The country code that you want the shipping address to be locked to. This can be useful to make sure the shipping address belongs to a given shipping country, e.g. the one selected in a country selector page. Not relevant if order contains only digital products.

attributes.coupon_code

string

The coupon code to be used for the order. If valid, it triggers a promotion adding a discount line item to the order.

attributes.gift_card_code

string

The gift card code (at least the first 8 characters) to be used for the order. If valid, it uses the gift card balance to pay for the order.

attributes.subtotal_amount_cents

integer

The sum of all the SKU line items total amounts, in cents.

attributes.subtotal_amount_float

float

The sum of all the SKU line items total amounts, float.

attributes.formatted_subtotal_amount

string

The sum of all the SKU line items total amounts, formatted.

attributes.shipping_amount_cents

integer

The sum of all the shipping costs, in cents.

attributes.shipping_amount_float

float

The sum of all the shipping costs, float.

attributes.formatted_shipping_amount

string

The sum of all the shipping costs, formatted.

attributes.payment_method_amount_cents

integer

The payment method costs, in cents.

attributes.payment_method_amount_float

float

The payment method costs, float.

attributes.formatted_payment_method_amount

string

The payment method costs, formatted.

attributes.discount_amount_cents

integer

The sum of all the discounts applied to the order, in cents (negative amount).

attributes.discount_amount_float

float

The sum of all the discounts applied to the order, float.

attributes.formatted_discount_amount

string

The sum of all the discounts applied to the order, formatted.

attributes.adjustment_amount_cents

integer

The sum of all the adjustments applied to the order, in cents.

attributes.adjustment_amount_float

float

The sum of all the adjustments applied to the order, float.

attributes.formatted_adjustment_amount

string

The sum of all the adjustments applied to the order, formatted.

attributes.gift_card_amount_cents

integer

The sum of all the gift_cards applied to the order, in cents.

attributes.gift_card_amount_float

float

The sum of all the gift_cards applied to the order, float.

attributes.formatted_gift_card_amount

string

The sum of all the gift_cards applied to the order, formatted.

attributes.total_tax_amount_cents

integer

The sum of all the taxes applied to the order, in cents.

attributes.total_tax_amount_float

float

The sum of all the taxes applied to the order, float.

attributes.formatted_total_tax_amount

string

The sum of all the taxes applied to the order, formatted.

attributes.subtotal_tax_amount_cents

integer

The taxes applied to the order's subtotal, in cents.

attributes.subtotal_tax_amount_float

float

The taxes applied to the order's subtotal, float.

attributes.formatted_subtotal_tax_amount

string

The taxes applied to the order's subtotal, formatted.

attributes.shipping_tax_amount_cents

integer

The taxes applied to the order's shipping costs, in cents.

attributes.shipping_tax_amount_float

float

The taxes applied to the order's shipping costs, float.

attributes.formatted_shipping_tax_amount

string

The taxes applied to the order's shipping costs, formatted.

attributes.payment_method_tax_amount_cents

integer

The taxes applied to the order's payment method costs, in cents.

attributes.payment_method_tax_amount_float

float

The taxes applied to the order's payment method costs, float.

attributes.formatted_payment_method_tax_amount

string

The taxes applied to the order's payment method costs, formatted.

attributes.adjustment_tax_amount_cents

integer

The taxes applied to the order adjustments, in cents.

attributes.adjustment_tax_amount_float

float

The taxes applied to the order adjustments, float.

attributes.formatted_adjustment_tax_amount

string

The taxes applied to the order adjustments, formatted.

attributes.total_amount_cents

integer

The order's total amount, in cents.

attributes.total_amount_float

float

The order's total amount, float.

attributes.formatted_total_amount

string

The order's total amount, formatted.

attributes.total_taxable_amount_cents

integer

The order's total taxable amount, in cents (without discounts).

attributes.total_taxable_amount_float

float

The order's total taxable amount, float.

attributes.formatted_total_taxable_amount

string

The order's total taxable amount, formatted.

attributes.subtotal_taxable_amount_cents

integer

The order's subtotal taxable amount, in cents (equal to subtotal_amount_cents when prices don't include taxes).

attributes.subtotal_taxable_amount_float

float

The order's subtotal taxable amount, float.

attributes.formatted_subtotal_taxable_amount

string

The order's subtotal taxable amount, formatted.

attributes.shipping_taxable_amount_cents

integer

The order's shipping taxable amount, in cents (equal to shipping_amount_cents when prices don't include taxes).

attributes.shipping_taxable_amount_float

float

The order's shipping taxable amount, float.

attributes.formatted_shipping_taxable_amount

string

The order's shipping taxable amount, formatted.

attributes.payment_method_taxable_amount_cents

integer

The order's payment method taxable amount, in cents (equal to payment_method_amount_cents when prices don't include taxes).

attributes.payment_method_taxable_amount_float

float

The order's payment method taxable amount, float.

attributes.formatted_payment_method_taxable_amount

string

The order's payment method taxable amount, formatted.

attributes.adjustment_taxable_amount_cents

integer

The order's adjustment taxable amount, in cents (equal to discount_adjustment_cents when prices don't include taxes).

attributes.adjustment_taxable_amount_float

float

The order's adjustment taxable amount, float.

attributes.formatted_adjustment_taxable_amount

string

The order's adjustment taxable amount, formatted.

attributes.total_amount_with_taxes_cents

integer

The order's total amount (when prices include taxes) or the order's total + taxes amount (when prices don't include taxes, e.g. US Markets or B2B).

attributes.total_amount_with_taxes_float

float

The order's total amount with taxes, float.

attributes.formatted_total_amount_with_taxes

string

The order's total amount with taxes, formatted.

attributes.fees_amount_cents

integer

The fees amount that is applied by Commerce Layer, in cents.

attributes.fees_amount_float

float

The fees amount that is applied by Commerce Layer, float.

attributes.formatted_fees_amount

string

The fees amount that is applied by Commerce Layer, formatted.

attributes.duty_amount_cents

integer

The duty amount that is calculated by external services, in cents.

attributes.duty_amount_float

float

The duty amount that is calculated by external services, float.

attributes.formatted_duty_amount

string

The duty amount that is calculated by external services, formatted.

attributes.place_total_amount_cents

integer

The total amount at place time, in cents, which is used internally for editing.

attributes.place_total_amount_float

float

The total amount at place time, float.

attributes.formatted_place_total_amount

string

The total amount at place time, formatted.

attributes.skus_count

integer

The total number of SKUs in the order's line items. This can be useful to display a preview of the customer shopping cart content.

attributes.line_item_options_count

integer

The total number of line item options. This can be useful to display a preview of the customer shopping cart content.

attributes.shipments_count

integer

The total number of shipments. This can be useful to manage the shipping method(s) selection during checkout.

attributes.tax_calculations_count

integer

The total number of tax calculations. This can be useful to monitor external tax service usage.

attributes.validations_count

integer

The total number of external validation performed. This can be useful to monitor if external validation has been triggered.

attributes.errors_count

integer

The total number of resource errors.

attributes.payment_source_details

object

An object that contains the shareable details of the order's payment source.

attributes.token

string

A unique token that can be shared more securely instead of the order's id.

attributes.cart_url

string

The cart url on your site. If present, it will be used on our hosted checkout application.

attributes.return_url

string

The return url on your site. If present, it will be used on our hosted checkout application.

attributes.terms_url

string

The terms and conditions url on your site. If present, it will be used on our hosted checkout application.

attributes.privacy_url

string

The privacy policy url on your site. If present, it will be used on our hosted checkout application.

attributes.checkout_url

string

The checkout url that was automatically generated for the order. Send the customers to this url to let them checkout the order securely on our hosted checkout application.

attributes._archive

boolean

Send this attribute if you want to archive the order.

attributes._unarchive

boolean

Send this attribute if you want to unarchive the order.

attributes._pending

boolean

Send this attribute if you want to move a draft or placing order to pending. Cannot be passed by sales channels.

attributes._place

boolean

Send this attribute if you want to place the order.

attributes._cancel

boolean

Send this attribute if you want to cancel a placed order. The order's authorization will be automatically voided.

attributes._approve

boolean

Send this attribute if you want to approve a placed order. Cannot be passed by sales channels.

attributes._approve_and_capture

boolean

Send this attribute if you want to approve and capture a placed order. Cannot be passed by sales channels.

attributes._authorize

boolean

Send this attribute if you want to authorize the order's payment source.

attributes._authorization_amount_cents