# Orders Commerce Layer Metrics API lets you perform different types of queries on the `/orders/{{query_type}}` endpoint to gather stats and information about your organization order history: {% content-ref url="orders/breakdown" %} [breakdown](https://docs.commercelayer.io/metrics-api-reference/resources/orders/breakdown) {% endcontent-ref %} {% content-ref url="orders/date-breakdown" %} [date-breakdown](https://docs.commercelayer.io/metrics-api-reference/resources/orders/date-breakdown) {% endcontent-ref %} {% content-ref url="orders/stats" %} [stats](https://docs.commercelayer.io/metrics-api-reference/resources/orders/stats) {% endcontent-ref %} {% content-ref url="orders/search" %} [search](https://docs.commercelayer.io/metrics-api-reference/resources/orders/search) {% endcontent-ref %} {% content-ref url="orders/export" %} [export](https://docs.commercelayer.io/metrics-api-reference/resources/orders/export) {% endcontent-ref %} The results of each query can be filtered based on specific fields and operators: {% content-ref url="orders/filters" %} [filters](https://docs.commercelayer.io/metrics-api-reference/resources/orders/filters) {% endcontent-ref %} You can easily see it in action by checking these simple examples: {% content-ref url="orders/examples" %} [examples](https://docs.commercelayer.io/metrics-api-reference/resources/orders/examples) {% endcontent-ref %} {% hint style="info" %} Commerce Layer Metrics API **Orders** collection includes *real orders* only, meaning [orders](https://app.gitbook.com/s/RWJeylueWkzLadK710XZ/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](https://docs.commercelayer.io/metrics-api-reference/resources/carts). {% endhint %} ## 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](https://en.wikipedia.org/wiki/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. | | **`company`** | String | The company specified in the address. | | **`first_name`** | String | The first name specified in the address. | | **`last_name`** | String | The last name 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). | | **`reference`** | String | Any external identifier that might be useful to link the customer 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. | #### `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](https://www.w3.org/TR/NOTE-datetime) standard). | | **`options`** | Object | The line item options (see the [related table](#line-item-options) 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](https://www.w3.org/TR/NOTE-datetime) 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](https://www.w3.org/TR/NOTE-datetime) 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. | | **`customer_type`** | String | The type of the associated customer. One of `new` or `returning`. | | **`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](https://www.w3.org/TR/NOTE-datetime) standard). | | **`archived_at`** | String | The date and time at which the order was archived (complete date plus hours, minutes and seconds — according to the [ISO 8601](https://www.w3.org/TR/NOTE-datetime) standard). | | **`archived`** | Boolean | Indicates if the order has been archived. | | **`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](https://www.w3.org/TR/NOTE-datetime) standard). | | **`country_code`** | String | The international 2-letter country code (as defined by the [ISO 3166-1](https://en.wikipedia.org/wiki/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](https://www.w3.org/TR/NOTE-datetime) standard). | | **`currency_code`** | String | The international 3-letter currency code (as defined by the [ISO 4217](https://en.wikipedia.org/wiki/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](https://www.w3.org/TR/NOTE-datetime) 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](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) 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](https://www.w3.org/TR/NOTE-datetime) 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](https://www.w3.org/TR/NOTE-datetime) 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](https://www.w3.org/TR/NOTE-datetime) 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](https://www.w3.org/TR/NOTE-datetime) 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. | | **`aggregated_details`** | String | Searchable field containing all orders data. | | **`link_id`** | String | The link ID used during the checkout. | | **`user_id`** | String | The user ID used to generate the link. | | **`store_id`** | String | The store ID used during the checkout. | | **`affiliate_code`** | String | The affiliate code used during the checkout. | #### `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](https://en.wikipedia.org/wiki/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. | #### `shipments` field | Attribute | Type | Description | | ------------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **`id`** | String | The shipment ID. | | **`number`** | String | The shipment number. | | **`items_count`** | Integer | The shipment items count. | | **`cost_amount`** | Integer | The shipment cost amount. | | **`status`** | String | The shipment status. | | **`cancelled_at`** | String | The date and time at which the shipment status was cancelled (complete date plus hours, minutes and seconds — according to the [ISO 8601](https://www.w3.org/TR/NOTE-datetime) standard). | | **`delivered_at`** | String | The date and time at which the shipment was delivered (complete date plus hours, minutes and seconds — according to the [ISO 8601](https://www.w3.org/TR/NOTE-datetime) standard). | | **`on_hold_at`** | String | The date and time at which the shipment status was put on hold (complete date plus hours, minutes and seconds — according to the [ISO 8601](https://www.w3.org/TR/NOTE-datetime) standard). | | **`picking_at`** | String | The date and time at which the shipment was picked (complete date plus hours, minutes and seconds — according to the [ISO 8601](https://www.w3.org/TR/NOTE-datetime) standard). | | **`packing_at`** | String | The date and time at which the shipment was packed (complete date plus hours, minutes and seconds — according to the [ISO 8601](https://www.w3.org/TR/NOTE-datetime) standard). | | **`ready_to_ship_at`** | String | The date and time at which the shipment was ready to ship (complete date plus hours, minutes and seconds — according to the [ISO 8601](https://www.w3.org/TR/NOTE-datetime) standard). | | **`shipped_at`** | String | The date and time at which the shipment was shipped (complete date plus hours, minutes and seconds — according to the [ISO 8601](https://www.w3.org/TR/NOTE-datetime) standard). | | **`created_at`** | String | The date and time at which the shipment was created (complete date plus hours, minutes and seconds — according to the [ISO 8601](https://www.w3.org/TR/NOTE-datetime) standard). | | **`updated_at`** | String | The date and time at which the shipment was updated (complete date plus hours, minutes and seconds — according to the [ISO 8601](https://www.w3.org/TR/NOTE-datetime) standard). | | **`reference`** | String | Any external identifier that might be useful to link the shipment 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. | | **`seconds_in_picking`** | Integer | The difference in seconds between `picking_at` and `packing_at` (`null` if the order hasn't been picked yet). | | **`seconds_in_ready_to_ship`** | Integer | The difference in seconds between `ready_to_ship_at` and `shipped_at` (`null` if the order hasn't been shipped yet). | | **`seconds_in_shipped`** | Integer | The difference in seconds between `delivered_at` and `shipped_at` (`null` if the order hasn't been delivered yet). | | **`fulfillment_time`** | Integer | The difference in seconds between `delivered_at` and `picking_at` or `shipped_at` and `picking_at`. | | **`items`** | String | Array of the shipment items information. | #### Shipment `stock_location` field | Attribute | Type | Description | | ---------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------ | | **`id`** | String | The shipment stock location ID. | | **`name`** | String | The shipment stock location name. | | **`reference`** | String | Any external identifier that might be useful to link the stock location reference 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. | #### Shipment `shipping_method` field | Attribute | Type | Description | | ---------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **`id`** | String | The shipment shipping method ID. | | **`name`** | String | The shipment shipping method name. | | **`reference`** | String | Any external identifier that might be useful to link the shipping method reference 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. | | **`currency_code`** | String | The international 3-letter currency code (as defined by the [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) standard), automatically inherited from the order's market. | #### Shipment `shipping_category` field | Attribute | Type | Description | | ---------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------- | | **`id`** | String | The shipment shipping category ID. | | **`name`** | String | The shipment shipping category name. | | **`reference`** | String | Any external identifier that might be useful to link the shipping method reference 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. | #### Shipment `tags` field | Attribute | Type | Description | | ---------- | ------ | ------------- | | **`id`** | String | The tag ID. | | **`name`** | String | The tag name. | #### `tags` field | Attribute | Type | Description | | ---------- | ------ | ------------- | | **`id`** | String | The tag ID. | | **`name`** | String | The tag name. | #### `resource_errors` field | Attribute | Type | Description | | ---------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **`code`** | String | The resource errors code. | | **`name`** | String | The name of the resource error. | | **`id`** | String | The ID of the resource error. | | **`message`** | String | The resource error message. | | **`created_at`** | String | The date and time at which the resource error was created (complete date plus hours, minutes and seconds — according to the [ISO 8601](https://www.w3.org/TR/NOTE-datetime) standard). | | **`updated_at`** | String | The date and time at which the resource error was updated (complete date plus hours, minutes and seconds — according to the [ISO 8601](https://www.w3.org/TR/NOTE-datetime) standard). |