Orders

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

Commerce Layer Metrics API lets you perform different types queries on the /orders/{{query_type}} endpoint to gather stats and information about your organization order history:
Breakdown
Date breakdown
Stats
Search
The results of each query can be filtered based on specific fields and operators:
Filters
You can easily see it in action by checking these simple examples:
Examples
Commerce Layer Metrics API Orders collection includes real orders only, meaning orders whose lifecycle starts from placement (i.e. placed, approved, or cancelled orders). If you need to do statistics on orders that are not placed yet (i.e. draft or pending orders), please refer to the Carts collection documentation.
Fields and attributes
Please reference to this list for a comprehensive view of all the order resource's fields and attributes, accessible through the Metrics API:
billing_address field
Attribute
Type
Description
business
Boolean
Indicates if the address is a business or a personal one.
city
String
The city specified in the address.
country_code
String
The international 2-letter country code (as defined by the ISO 3166-1 standard) specified in the address.
geocoded
Boolean
Indicates if the address has been successfully geocoded.
localized
Boolean
Indicates if the latitude and longitude of the address are present, either geocoded or manually updated.
state_code
String
The state, province or region code specified in the address.
zip_code
String
The ZIP or postal code specified in the address.
customer field
Attribute
Type
Description
id
String
The ID of the customer.
email
String
The email address of the customer.
group_name
String
The name of the customer group the customer belongs to (if any).
line_items field
Attribute
Type
Description
code
String
The code of the associated SKU or bundle.
discount
Number
The discount applied to the line item (float).
id
String
The ID of the line item.
item_id
String
The ID of the associated item.
item_type
String
The type of the associated item. One of sku, bundle, shipment, payment_method, adjustment, gift_card, or a valid promotion type (e.g. percentage_discount_promotion, free_shipping_promotion, etc.).
name
String
The name of the line item. When missing, it gets populated with the name of the associated item (if present).
options_amount
Number
The amount of the line item option (float).
quantity
Integer
The line item's quantity.
tax_amount
Number
The collected tax amount for the line item (float). Otherwise calculated as the line item's (total_amount - discount) * tax_rate (float).
tax_rate
Number
The tax rate for the line item (if calculated).
total_amount
Number
The total amount of the line item (float). Calculated as the line item's unit_amount * quantity + plus the associated line item options amount.
unit_amount
Number
The unit amount of the line item (float).
updated_at
String
The date and time at which the line item was last updated (complete date plus hours, minutes and seconds — according to the ISO 8601 standard).
options
Object
The line item options (see the related table for all the single option objects attributes).
Line item options field
Attribute
Type
Description
id
String
The ID of the line item option.
name
String
The name of the line item option. When missing, it gets populated with the name of the associated SKU option.
quantity
Integer
The line item option's quantity.
total_amount
Number
The total amount of the line item option (float). Calculated as the line item option's unit_amount * quantity.
unit_amount
Number
The unit amount of the line item option (float).
market field
Attribute
Type
Description
id
String
The ID of the market.
name
String
The name of the market.
number
Integer
The numeric unique identifier for the market.
order field
Attribute
Type
Description
date_from
String
The lower limit of the date and time range used to filter the collected orders (complete date plus hours, minutes and seconds — according to the ISO 8601 standard).
date_to
String
The upper limit of the date and time range used to filter the collected orders (complete date plus hours, minutes and seconds — according to the ISO 8601 standard).
date_field
String
The date field (e.g. created_at, updated_at, etc.) where to apply the date and time range filter.
discounted
Boolean
Indicates a discount has been applied to the order.
refunded
Boolean
Indicates if the order has been partially or totally refunded.
gift_card
Boolean
Indicates if a gift card has been (or is set to be) used to pay — in total or in part - for the order.
coupon
Boolean
Indicates if a coupon code has been (or is set to be) used to pay — in total or in part — for the order.
returned
Boolean
Indicates if a return is associated with the order.
options
Boolean
Indicates if at least one line item of the order has at least an option.
adjustment_amount
Number
The sum of all the adjustments applied to the order (float).
adjustment_tax_amount
Number
The taxes applied to the order's adjustments (float).
adjustment_taxable_amount
Number
The order's adjustment taxable amount (float).
approved_at
String
The date and time at which the order was approved (complete date plus hours, minutes and seconds — according to the ISO 8601 standard).
cancelled_at
String
The date and time at which the order was cancelled (complete date plus hours, minutes and seconds — according to the ISO 8601 standard).
country_code
String
The international 2-letter country code (as defined by the ISO 3166-1 standard), automatically inherited from the order's shipping address.
coupon_code
String
The coupon code to be used to pay — in total or in part — for the order. If valid, it triggers a promotion adding a discount line item to the order.
created_at
String
The date and time at which the order was created (complete date plus hours, minutes and seconds — according to the ISO 8601 standard).
currency_code
String
The international 3-letter currency code (as defined by the ISO 4217 standard), automatically inherited from the order's market.
discount_amount
Number
The sum of all the discounts applied to the order (float).
duty_amount
Number
The duty amount that is calculated by external services (float).
freight_taxable
Boolean
Indicates if taxes are applied to shipping costs.
fulfillment_status
String
The order's fulfillment status. One of unfulfilled (default), in_progress, or fulfilled.
fulfillment_updated_at
String
The date and time at which the order's fulfillment status was last updated (complete date plus hours, minutes and seconds — according to the ISO 8601 standard).
gift_card_code
String
The gift card code (at least the first 8 characters) to be used to pay — in total or in part — for the order. If valid, it uses the associated gift card balance.
gift_card_amount
Number
The sum of all the gift cards applied to the order (float).
guest
Boolean
Indicates if the order has been placed as guest (by a non-logged in customer).
id
String
The ID of the order.
language_code
String
The preferred language code (as defined by the ISO 639-1 standard) to be used when communicating with the customer when checking out the order.
line_item_options_count
Integer
The total number of line item options associated with the order's line items.
number
Integer
The numeric unique identifier for the order.
payment_method_amount
Number
The costs of the payment method associated with the order (float).
payment_method_tax_amount
Number
The taxes applied to the order's payment method costs (float).
payment_method_taxable_amount
Number
The order's payment method taxable amount (float).
payment_status
String
The order's payment status. One of unpaid (default), authorized, partially_authorized, paid, partially_paid, voided, partially_voided, refunded, partially_refunded or free.
payment_updated_at
String
The date and time at which the order's payment status was last updated (complete date plus hours, minutes and seconds — according to the ISO 8601 standard).
placed_at
String
The date and time at which the order was placed (complete date plus hours, minutes and seconds — according to the ISO 8601 standard).
reference
String
Any external identifier that might be useful to link the order resource to other systems through the Commerce Layer core API.
reference_origin
String
Any identifier of the 3rd-party system that defines the reference code.
shipments_count
Integer
The total number of shipments associated with the order.
shipping_amount
Number
The sum of all the shipping costs of the order (float).
shipping_taxable_amount
Number
The order's shipping taxable amount (float).
skus_count
Integer
The total number of SKUs in the order's line items.
status
String
The order status. One of placed, approved, or cancelled.
subtotal_amount
Number
The sum of all the SKU line items total amounts (float).
subtotal_tax_amount
Number
The taxes applied to the order's subtotal (float).
subtotal_taxable_amount
Number
The order's subtotal taxable amount (float).
tax_included
Boolean
Indicates if taxes are included in the order amounts (automatically inherited from the order's price list).
total_amount
Number
The order's total amount (float).
total_amount_with_taxes
Number
The order's total amount, taxes included (float).
total_tax_amount
Number
The sum of all the taxes applied to the order (float).
total_taxable_amount
Number
The order's total taxable amount (float).
updated_at
String
The date and time at which the order was last updated (complete date plus hours, minutes and seconds — according to the ISO 8601 standard).
current_date
String
The date and time of the order's latest status change, regardless of the order's status (complete date plus hours, minutes and seconds — according to the ISO 8601 standard).
seconds_in_draft
Integer
The difference in seconds between placed_at and created_at (null if the order hasn't been placed yet).
seconds_in_approved
Integer
The difference in seconds between cancelled_at and approved_at (null if the order hasn't been approved yet or no further status change happened after approval — e.g. the order has been regularly fulfilled).
seconds_in_placed
Integer
The difference in seconds between approved_at and placed_at if the order has been approved or between cancelled_at and placed_at if the order has been cancelled before approval (null if the order hasn't been placed yet or no further status change happened after placement).
placed_day_of_week
Integer
The day of week when the order was placed, expressed as an integer (0 through 6, from Sunday to Saturday — e.g. 1 is Monday).
refunds_total_amount_with_taxes
Integer
Total amount of refunds (including taxes) associated with the order.
total_amount_with_taxes_net_of_refunds
Number
The total amount of the order minus the total amount of refunds.
payment_method field
Attribute
Type
Description
id
String
The ID of the payment method.
source_type
String
The payment source type. One of AdyenPayment, BraintreePayment, CheckoutComPayment, CreditCard, ExternalPayment, KlarnaPayment, PaypalPayment, StripePayment, or WireTransfer.
name
String
The payment source type, titleized.
moto
Boolean
Indicates if the payment has been marked as MOTO (must be supported by the payment gateway).
issuer
String
The payment method's issuer (if present and provided by the payment gateway).
issuer_type
String
The type of issuer (if present and provided by the payment gateway).
card_type
String
The type of card used to pay for the order (if present and provided by the payment gateway).
refunds field
Attribute
Type
Description
id
String
The ID of the refund.
amount
Number
The refunded amount (float).
number
String
The transaction number associated with the refund (auto-generated).
shipping_address field
Attribute
Type
Description
business
Boolean
Indicates if the address is a business or a personal one.
city
String
The city specified in the address.
country_code
String
The international 2-letter country code (as defined by the ISO 3166-1 standard) specified in the address.
geocoded
Boolean
Indicates if the address has been successfully geocoded.
localized
Boolean
Indicates if the latitude and longitude of the address are present, either geocoded or manually updated.
state_code
String
The state, province or region code specified in the address.
zip_code
String
The ZIP or postal code specified in the address.
tags field
Attribute
Type
Description
id
String
The tag ID.
name
String
The tag name.

Attribute	Type	Description
`business`	Boolean	Indicates if the address is a business or a personal one.
`city`	String	The city specified in the address.
`country_code`	String	The international 2-letter country code (as defined by the ISO 3166-1 standard) specified in the address.
`geocoded`	Boolean	Indicates if the address has been successfully geocoded.
`localized`	Boolean	Indicates if the latitude and longitude of the address are present, either geocoded or manually updated.
`state_code`	String	The state, province or region code specified in the address.
`zip_code`	String	The ZIP or postal code specified in the address.

Attribute	Type	Description
`id`	String	The ID of the customer.
`email`	String	The email address of the customer.
`group_name`	String	The name of the customer group the customer belongs to (if any).

Attribute	Type	Description
`code`	String	The code of the associated SKU or bundle.
`discount`	Number	The discount applied to the line item (float).
`id`	String	The ID of the line item.
`item_id`	String	The ID of the associated item.
`item_type`	String	The type of the associated item. One of `sku`, `bundle`, `shipment`, `payment_method`, `adjustment`, `gift_card`, or a valid promotion type (e.g. `percentage_discount_promotion`, `free_shipping_promotion`, etc.).
`name`	String	The name of the line item. When missing, it gets populated with the name of the associated item (if present).
`options_amount`	Number	The amount of the line item option (float).
`quantity`	Integer	The line item's quantity.
`tax_amount`	Number	The collected tax amount for the line item (float). Otherwise calculated as the line item's `(total_amount - discount) * tax_rate` (float).
`tax_rate`	Number	The tax rate for the line item (if calculated).
`total_amount`	Number	The total amount of the line item (float). Calculated as the line item's `unit_amount * quantity` + plus the associated line item options amount.
`unit_amount`	Number	The unit amount of the line item (float).
`updated_at`	String	The date and time at which the line item was last updated (complete date plus hours, minutes and seconds — according to the ISO 8601 standard).
`options`	Object	The line item options (see the related table for all the single option objects attributes).

Attribute	Type	Description
`id`	String	The ID of the line item option.
`name`	String	The name of the line item option. When missing, it gets populated with the name of the associated SKU option.
`quantity`	Integer	The line item option's quantity.
`total_amount`	Number	The total amount of the line item option (float). Calculated as the line item option's `unit_amount * quantity`.
`unit_amount`	Number	The unit amount of the line item option (float).

Attribute	Type	Description
`id`	String	The ID of the market.
`name`	String	The name of the market.
`number`	Integer	The numeric unique identifier for the market.

Attribute	Type	Description
`date_from`	String	The lower limit of the date and time range used to filter the collected orders (complete date plus hours, minutes and seconds — according to the ISO 8601 standard).
`date_to`	String	The upper limit of the date and time range used to filter the collected orders (complete date plus hours, minutes and seconds — according to the ISO 8601 standard).
`date_field`	String	The date field (e.g. `created_at`, `updated_at`, etc.) where to apply the date and time range filter.
`discounted`	Boolean	Indicates a discount has been applied to the order.
`refunded`	Boolean	Indicates if the order has been partially or totally refunded.
`gift_card`	Boolean	Indicates if a gift card has been (or is set to be) used to pay — in total or in part - for the order.
`coupon`	Boolean	Indicates if a coupon code has been (or is set to be) used to pay — in total or in part — for the order.
`returned`	Boolean	Indicates if a return is associated with the order.
`options`	Boolean	Indicates if at least one line item of the order has at least an option.
`adjustment_amount`	Number	The sum of all the adjustments applied to the order (float).
`adjustment_tax_amount`	Number	The taxes applied to the order's adjustments (float).
`adjustment_taxable_amount`	Number	The order's adjustment taxable amount (float).
`approved_at`	String	The date and time at which the order was approved (complete date plus hours, minutes and seconds — according to the ISO 8601 standard).
`cancelled_at`	String	The date and time at which the order was cancelled (complete date plus hours, minutes and seconds — according to the ISO 8601 standard).
`country_code`	String	The international 2-letter country code (as defined by the ISO 3166-1 standard), automatically inherited from the order's shipping address.
`coupon_code`	String	The coupon code to be used to pay — in total or in part — for the order. If valid, it triggers a promotion adding a discount line item to the order.
`created_at`	String	The date and time at which the order was created (complete date plus hours, minutes and seconds — according to the ISO 8601 standard).
`currency_code`	String	The international 3-letter currency code (as defined by the ISO 4217 standard), automatically inherited from the order's market.
`discount_amount`	Number	The sum of all the discounts applied to the order (float).
`duty_amount`	Number	The duty amount that is calculated by external services (float).
`freight_taxable`	Boolean	Indicates if taxes are applied to shipping costs.
`fulfillment_status`	String	The order's fulfillment status. One of `unfulfilled` (default), `in_progress`, or `fulfilled`.
`fulfillment_updated_at`	String	The date and time at which the order's fulfillment status was last updated (complete date plus hours, minutes and seconds — according to the ISO 8601 standard).
`gift_card_code`	String	The gift card code (at least the first 8 characters) to be used to pay — in total or in part — for the order. If valid, it uses the associated gift card balance.
`gift_card_amount`	Number	The sum of all the gift cards applied to the order (float).
`guest`	Boolean	Indicates if the order has been placed as guest (by a non-logged in customer).
`id`	String	The ID of the order.
`language_code`	String	The preferred language code (as defined by the ISO 639-1 standard) to be used when communicating with the customer when checking out the order.
`line_item_options_count`	Integer	The total number of line item options associated with the order's line items.
`number`	Integer	The numeric unique identifier for the order.
`payment_method_amount`	Number	The costs of the payment method associated with the order (float).
`payment_method_tax_amount`	Number	The taxes applied to the order's payment method costs (float).
`payment_method_taxable_amount`	Number	The order's payment method taxable amount (float).
`payment_status`	String	The order's payment status. One of `unpaid` (default), `authorized`, `partially_authorized`, `paid`, `partially_paid`, `voided`, `partially_voided`, `refunded`, `partially_refunded` or `free`.
`payment_updated_at`	String	The date and time at which the order's payment status was last updated (complete date plus hours, minutes and seconds — according to the ISO 8601 standard).
`placed_at`	String	The date and time at which the order was placed (complete date plus hours, minutes and seconds — according to the ISO 8601 standard).
`reference`	String	Any external identifier that might be useful to link the order resource to other systems through the Commerce Layer core API.
`reference_origin`	String	Any identifier of the 3rd-party system that defines the reference code.
`shipments_count`	Integer	The total number of shipments associated with the order.
`shipping_amount`	Number	The sum of all the shipping costs of the order (float).
`shipping_taxable_amount`	Number	The order's shipping taxable amount (float).
`skus_count`	Integer	The total number of SKUs in the order's line items.
`status`	String	The order status. One of `placed`, `approved`, or `cancelled`.
`subtotal_amount`	Number	The sum of all the SKU line items total amounts (float).
`subtotal_tax_amount`	Number	The taxes applied to the order's subtotal (float).
`subtotal_taxable_amount`	Number	The order's subtotal taxable amount (float).
`tax_included`	Boolean	Indicates if taxes are included in the order amounts (automatically inherited from the order's price list).
`total_amount`	Number	The order's total amount (float).
`total_amount_with_taxes`	Number	The order's total amount, taxes included (float).
`total_tax_amount`	Number	The sum of all the taxes applied to the order (float).
`total_taxable_amount`	Number	The order's total taxable amount (float).
`updated_at`	String	The date and time at which the order was last updated (complete date plus hours, minutes and seconds — according to the ISO 8601 standard).
`current_date`	String	The date and time of the order's latest status change, regardless of the order's status (complete date plus hours, minutes and seconds — according to the ISO 8601 standard).
`seconds_in_draft`	Integer	The difference in seconds between `placed_at` and `created_at` (`null` if the order hasn't been placed yet).
`seconds_in_approved`	Integer	The difference in seconds between `cancelled_at` and `approved_at` (`null` if the order hasn't been approved yet or no further status change happened after approval — e.g. the order has been regularly fulfilled).
`seconds_in_placed`	Integer	The difference in seconds between `approved_at` and `placed_at` if the order has been approved or between `cancelled_at` and `placed_at` if the order has been cancelled before approval (`null` if the order hasn't been placed yet or no further status change happened after placement).
`placed_day_of_week`	Integer	The day of week when the order was placed, expressed as an integer (`0` through `6`, from Sunday to Saturday — e.g. `1` is Monday).
`refunds_total_amount_with_taxes`	Integer	Total amount of refunds (including taxes) associated with the order.
`total_amount_with_taxes_net_of_refunds`	Number	The total amount of the order minus the total amount of refunds.

Attribute	Type	Description
`id`	String	The ID of the payment method.
`source_type`	String	The payment source type. One of `AdyenPayment`, `BraintreePayment`, `CheckoutComPayment`, `CreditCard`, `ExternalPayment`, `KlarnaPayment`, `PaypalPayment`, `StripePayment`, or `WireTransfer`.
`name`	String	The payment source type, titleized.
`moto`	Boolean	Indicates if the payment has been marked as MOTO (must be supported by the payment gateway).
`issuer`	String	The payment method's issuer (if present and provided by the payment gateway).
`issuer_type`	String	The type of issuer (if present and provided by the payment gateway).
`card_type`	String	The type of card used to pay for the order (if present and provided by the payment gateway).

Attribute	Type	Description
`id`	String	The ID of the refund.
`amount`	Number	The refunded amount (float).
`number`	String	The transaction number associated with the refund (auto-generated).

Attribute	Type	Description
`business`	Boolean	Indicates if the address is a business or a personal one.
`city`	String	The city specified in the address.
`country_code`	String	The international 2-letter country code (as defined by the ISO 3166-1 standard) specified in the address.
`geocoded`	Boolean	Indicates if the address has been successfully geocoded.
`localized`	Boolean	Indicates if the latitude and longitude of the address are present, either geocoded or manually updated.
`state_code`	String	The state, province or region code specified in the address.
`zip_code`	String	The ZIP or postal code specified in the address.

Attribute	Type	Description
`id`	String	The tag ID.
`name`	String	The tag name.

Introduction

Breakdown

Last modified 4mo ago

Orders

Fields and attributes

`billing_address` field

`customer` field

`line_items` field

Line item `options` field

`market` field

`order` field

`payment_method` field

`refunds` field

`shipping_address` field

`tags` field