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 |
|
|
id |
| The order unique identifier |
links.self |
| The order endpoint URL |
attributes.number |
| 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 |
| The affiliate code, if any, the seller will transfer commission on shop by link transactions. |
attributes.autorefresh |
| Save this attribute as 'false' if you want prevent the order to be refreshed automatically at each change (much faster). |
attributes.place_async |
| Save this attribute as 'true' if you want perform the place asynchronously. Payment errors, if any, will be collected afterwards. |
attributes.status |
| The order status. One of 'draft' (default), 'pending', 'editing', 'placing', 'placed', 'approved', or 'cancelled'. |
attributes.payment_status |
| 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 |
| The order fulfillment status. One of 'unfulfilled' (default), 'in_progress', 'fulfilled', or 'not_required'. |
attributes.guest |
| Indicates if the order has been placed as guest. |
attributes.editable |
| Indicates if the order can be edited. |
attributes.customer_email |
| 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 |
| 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 |
| 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 |
| The international 3-letter currency code as defined by the ISO 4217 standard, automatically inherited from the order's market. |
attributes.tax_included |
| Indicates if taxes are included in the order amounts, automatically inherited from the order's price list. |
attributes.tax_rate |
| The tax rate for this order (if calculated). |
attributes.freight_taxable |
| Indicates if taxes are applied to shipping costs. |
attributes.payment_method_taxable |
| Indicates if taxes are applied to payment methods costs. |
attributes.adjustment_taxable |
| Indicates if taxes are applied to positive adjustments. |
attributes.gift_card_taxable |
| Indicates if taxes are applied to purchased gift cards. |
attributes.requires_billing_info |
| Indicates if the billing address associated to this order requires billing info to be present. |
attributes.country_code |
| 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 |
| 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 |
| 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 |
| 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 |
| The sum of all the SKU line items total amounts, in cents. |
attributes.subtotal_amount_float |
| The sum of all the SKU line items total amounts, float. |
attributes.formatted_subtotal_amount |
| The sum of all the SKU line items total amounts, formatted. |
attributes.shipping_amount_cents |
| The sum of all the shipping costs, in cents. |
attributes.shipping_amount_float |
| The sum of all the shipping costs, float. |
attributes.formatted_shipping_amount |
| The sum of all the shipping costs, formatted. |
attributes.payment_method_amount_cents |
| The payment method costs, in cents. |
attributes.payment_method_amount_float |
| The payment method costs, float. |
attributes.formatted_payment_method_amount |
| The payment method costs, formatted. |
attributes.discount_amount_cents |
| The sum of all the discounts applied to the order, in cents (negative amount). |
attributes.discount_amount_float |
| The sum of all the discounts applied to the order, float. |
attributes.formatted_discount_amount |
| The sum of all the discounts applied to the order, formatted. |
attributes.adjustment_amount_cents |
| The sum of all the adjustments applied to the order, in cents. |
attributes.adjustment_amount_float |
| The sum of all the adjustments applied to the order, float. |
attributes.formatted_adjustment_amount |
| The sum of all the adjustments applied to the order, formatted. |
attributes.gift_card_amount_cents |
| The sum of all the gift_cards applied to the order, in cents. |
attributes.gift_card_amount_float |
| The sum of all the gift_cards applied to the order, float. |
attributes.formatted_gift_card_amount |
| The sum of all the gift_cards applied to the order, formatted. |
attributes.total_tax_amount_cents |
| The sum of all the taxes applied to the order, in cents. |
attributes.total_tax_amount_float |
| The sum of all the taxes applied to the order, float. |
attributes.formatted_total_tax_amount |
| The sum of all the taxes applied to the order, formatted. |
attributes.subtotal_tax_amount_cents |
| The taxes applied to the order's subtotal, in cents. |
attributes.subtotal_tax_amount_float |
| The taxes applied to the order's subtotal, float. |
attributes.formatted_subtotal_tax_amount |
| The taxes applied to the order's subtotal, formatted. |
attributes.shipping_tax_amount_cents |
| The taxes applied to the order's shipping costs, in cents. |
attributes.shipping_tax_amount_float |
| The taxes applied to the order's shipping costs, float. |
attributes.formatted_shipping_tax_amount |
| The taxes applied to the order's shipping costs, formatted. |
attributes.payment_method_tax_amount_cents |
| The taxes applied to the order's payment method costs, in cents. |
attributes.payment_method_tax_amount_float |
| The taxes applied to the order's payment method costs, float. |
attributes.formatted_payment_method_tax_amount |
| The taxes applied to the order's payment method costs, formatted. |
attributes.adjustment_tax_amount_cents |
| The taxes applied to the order adjustments, in cents. |
attributes.adjustment_tax_amount_float |
| The taxes applied to the order adjustments, float. |
attributes.formatted_adjustment_tax_amount |
| The taxes applied to the order adjustments, formatted. |
attributes.total_amount_cents |
| The order's total amount, in cents. |
attributes.total_amount_float |
| The order's total amount, float. |
attributes.formatted_total_amount |
| The order's total amount, formatted. |
attributes.total_taxable_amount_cents |
| The order's total taxable amount, in cents (without discounts). |
attributes.total_taxable_amount_float |
| The order's total taxable amount, float. |
attributes.formatted_total_taxable_amount |
| The order's total taxable amount, formatted. |
attributes.subtotal_taxable_amount_cents |
| The order's subtotal taxable amount, in cents (equal to subtotal_amount_cents when prices don't include taxes). |
attributes.subtotal_taxable_amount_float |
| The order's subtotal taxable amount, float. |
attributes.formatted_subtotal_taxable_amount |
| The order's subtotal taxable amount, formatted. |
attributes.shipping_taxable_amount_cents |
| The order's shipping taxable amount, in cents (equal to shipping_amount_cents when prices don't include taxes). |
attributes.shipping_taxable_amount_float |
| The order's shipping taxable amount, float. |
attributes.formatted_shipping_taxable_amount |
| The order's shipping taxable amount, formatted. |
attributes.payment_method_taxable_amount_cents |
| 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 |
| The order's payment method taxable amount, float. |
attributes.formatted_payment_method_taxable_amount |
| The order's payment method taxable amount, formatted. |
attributes.adjustment_taxable_amount_cents |
| The order's adjustment taxable amount, in cents (equal to discount_adjustment_cents when prices don't include taxes). |
attributes.adjustment_taxable_amount_float |
| The order's adjustment taxable amount, float. |
attributes.formatted_adjustment_taxable_amount |
| The order's adjustment taxable amount, formatted. |
attributes.total_amount_with_taxes_cents |
| 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 |
| The order's total amount with taxes, float. |
attributes.formatted_total_amount_with_taxes |
| The order's total amount with taxes, formatted. |
attributes.fees_amount_cents |
| The fees amount that is applied by Commerce Layer, in cents. |
attributes.fees_amount_float |
| The fees amount that is applied by Commerce Layer, float. |
attributes.formatted_fees_amount |
| The fees amount that is applied by Commerce Layer, formatted. |
attributes.duty_amount_cents |
| The duty amount that is calculated by external services, in cents. |
attributes.duty_amount_float |
| The duty amount that is calculated by external services, float. |
attributes.formatted_duty_amount |
| The duty amount that is calculated by external services, formatted. |
attributes.place_total_amount_cents |
| The total amount at place time, in cents, which is used internally for editing. |
attributes.place_total_amount_float |
| The total amount at place time, float. |
attributes.formatted_place_total_amount |
| The total amount at place time, formatted. |
attributes.skus_count |
| 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 |
| The total number of line item options. This can be useful to display a preview of the customer shopping cart content. |
attributes.shipments_count |
| The total number of shipments. This can be useful to manage the shipping method(s) selection during checkout. |
attributes.tax_calculations_count |
| The total number of tax calculations. This can be useful to monitor external tax service usage. |
attributes.validations_count |
| The total number of external validation performed. This can be useful to monitor if external validation has been triggered. |
attributes.errors_count |
| The total number of resource errors. |
attributes.payment_source_details |
| An object that contains the shareable details of the order's payment source. |
attributes.token |
| A unique token that can be shared more securely instead of the order's id. |
attributes.cart_url |
| The cart url on your site. If present, it will be used on our hosted checkout application. |
attributes.return_url |
| The return url on your site. If present, it will be used on our hosted checkout application. |
attributes.terms_url |
| The terms and conditions url on your site. If present, it will be used on our hosted checkout application. |
attributes.privacy_url |
| The privacy policy url on your site. If present, it will be used on our hosted checkout application. |
attributes.checkout_url |
| 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 |
| Send this attribute if you want to archive the order. |
attributes._unarchive |
| Send this attribute if you want to unarchive the order. |
attributes._pending |
| Send this attribute if you want to move a draft or placing order to pending. Cannot be passed by sales channels. |
attributes._place |
| Send this attribute if you want to place the order. |
attributes._cancel |
| Send this attribute if you want to cancel a placed order. The order's authorization will be automatically voided. |
attributes._approve |
| Send this attribute if you want to approve a placed order. Cannot be passed by sales channels. |
attributes._approve_and_capture |
| Send this attribute if you want to approve and capture a placed order. Cannot be passed by sales channels. |
attributes._authorize |
| Send this attribute if you want to authorize the order's payment source. |
attributes._authorization_amount_cents |
| Send this attribute as a value in cents if you want to overwrite the amount to be authorized. |
attributes._capture |
| Send this attribute if you want to capture an authorized order. Cannot be passed by sales channels. |
attributes._refund |
| Send this attribute if you want to refund a captured order. Cannot be passed by sales channels. |
attributes._fulfill |
| Send this attribute if you want to mark as fulfilled the order (shipments must be cancelled, shipped or delivered). Cannot be passed by sales channels. |
attributes._update_taxes |
| Send this attribute if you want to force tax calculation for this order (a tax calculator must be associated to the order's market). |
attributes._nullify_payment_source |
| Send this attribute if you want to nullify the payment source for this order. |
attributes._billing_address_clone_id |
| The id of the address that you want to clone to create the order's billing address. |
attributes._shipping_address_clone_id |
| The id of the address that you want to clone to create the order's shipping address. |
attributes._customer_payment_source_id |
| The id of the customer payment source (i.e. credit card) that you want to use as the order's payment source. |
attributes._shipping_address_same_as_billing |
| Send this attribute if you want the shipping address to be cloned from the order's billing address. |
attributes._billing_address_same_as_shipping |
| Send this attribute if you want the billing address to be cloned from the order's shipping address. |
attributes._commit_invoice |
| Send this attribute if you want commit the sales tax invoice to the associated tax calculator (currently supported by Avalara). |
attributes._refund_invoice |
| Send this attribute if you want refund the sales tax invoice to the associated tax calculator (currently supported by Avalara). |
attributes._save_payment_source_to_customer_wallet |
| Send this attribute if you want the order's payment source to be saved in the customer's wallet as a customer payment source. |
attributes._save_shipping_address_to_customer_address_book |
| Send this attribute if you want the order's shipping address to be saved in the customer's address book as a customer address. |
attributes._save_billing_address_to_customer_address_book |
| Send this attribute if you want the order's billing address to be saved in the customer's address book as a customer address. |
attributes._refresh |
| Send this attribute if you want to manually refresh the order. |
attributes._validate |
| Send this attribute if you want to trigger the external validation for the order. |
attributes._create_subscriptions |
| Send this attribute upon/after placing the order if you want to create order subscriptions from the line items that have a frequency. |
attributes._start_editing |
| Send this attribute if you want to edit the order after it is placed. Remember you cannot exceed the original total amount. Cannot be passed by sales channels. |
attributes._stop_editing |
| Send this attribute to stop the editing for the order and return back to placed status. Cannot be passed by sales channels. |
attributes.placed_at |
| Time at which the order was placed. |
attributes.approved_at |
| Time at which the order was approved. |
attributes.cancelled_at |
| Time at which the order was cancelled. |
attributes.payment_updated_at |
| Time at which the order's payment status was last updated. |
attributes.fulfillment_updated_at |
| Time at which the order's fulfillment status was last updated. |
attributes.refreshed_at |
| Last time at which an order was manually refreshed. |
attributes.archived_at |
| Time at which the resource has been archived. |
attributes.subscription_created_at |
| Time at which the order has been marked to create a subscription from its recurring line items. |
attributes.circuit_state |
| The circuit breaker state, by default it is 'closed'. It can become 'open' once the number of consecutive failures overlaps the specified threshold, in such case no further calls to the failing callback are made. |
attributes.circuit_failure_count |
| The number of consecutive failures recorded by the circuit breaker associated to this resource, will be reset on first successful call to callback. |
attributes._reset_circuit |
| Send this attribute if you want to reset the circuit breaker associated to this resource to 'closed' state and zero failures count. Cannot be passed by sales channels. |
attributes.created_at |
| Time at which the resource was created. |
attributes.updated_at |
| Time at which the resource was last updated. |
attributes.reference |
| A string that you can use to add any external identifier to the resource. This can be useful for integrating the resource to an external system, like an ERP, a marketing tool, a CRM, or whatever. |
attributes.reference_origin |
| Any identifier of the third party system that defines the reference code. |
attributes.metadata |
| Set of key-value pairs that you can attach to the resource. This can be useful for storing additional information about the resource in a structured format. |
relationships.market |
| The associated market. |
relationships.customer |
| The associated customer. |
relationships.shipping_address |
| The customer's shipping address. |
relationships.billing_address |
| The customer's billing address. |
relationships.available_payment_methods |
| The available payment methods for the order. Useful to present the customer with a list of choices during the checkout. Only enabled payment methods are included in the list. |
relationships.available_customer_payment_sources |
| The available customer payment sources for the order. Useful to present the customer with a list of choices during the checkout. |
relationships.available_free_skus |
| The available SKUs eligible as free gifts once added to the order. Useful to present the customer with a list of possible free gifts during the checkout. The list is filled by SKUs which belongs to matching free gift promotions. |
relationships.available_free_bundles |
| The available bundles eligible as free gifts once added to the order. Useful to present the customer with a list of possible free gifts during the checkout. The list is filled by bundles which belongs to matching free gift promotions. |
relationships.payment_method |
| The associated payment method. |
relationships.payment_source |
| The associated payment source. |
relationships.line_items |
| The associated line items. |
relationships.line_item_options |
| The associated line item options. |
relationships.stock_reservations |
| The associated stock reservations. |
relationships.stock_line_items |
| The associated stock line items. |
relationships.stock_transfers |
| The associated stock transfers. |
relationships.shipments |
| The associated shipments (automatically generated based on the inventory model). |
relationships.payment_options |
| The associated payment options. |
relationships.transactions |
| The associated transactions. |
relationships.authorizations |
| The associated authorizations. |
relationships.captures |
| The associated captures. |
relationships.voids |
| The associated voids. |
relationships.refunds |
| The associated refunds. |
relationships.returns |
| The associated returns. |
relationships.order_subscription |
| The target order associated subscription. |
relationships.order_subscriptions |
| The source order associated subscriptions. |
relationships.order_factories |
| The associated order copies. |
relationships.order_copies |
| The associated order copies. |
relationships.recurring_order_copies |
| The associated recurring order copies. |
relationships.attachments |
| The associated attachments. |
relationships.links |
| The associated links. |
relationships.resource_errors |
| The associated resource errors. |
relationships.events |
| The associated events. |
relationships.tags |
| The associated tags. |
relationships.versions |
| The associated changes. |
meta.mode |
| The resource environment (can be one of |
Last updated