# Carts Within Commerce Layer, every order that's not yet placed acts as a shopping cart. [Orders](/core-api-reference/orders.md) get created in *draft* status and become *pending* when they have a customer and some line items associated. Commerce Layer Metrics API cart addresses this subset of orders — the ones that are in *draft* or *pending* status — and lets you perform different types of queries on the `/carts/{{query_type}}` endpoint to gather stats and information about your organization cart history: {% content-ref url="/pages/4PMkKyoNosKF6AYrXQeT" %} [Breakdown](/metrics-api-reference/resources/carts/breakdown.md) {% endcontent-ref %} {% content-ref url="/pages/42dHImmAbKHHtfC59RAJ" %} [Date breakdown](/metrics-api-reference/resources/carts/date-breakdown.md) {% endcontent-ref %} {% content-ref url="/pages/Aap3gPhuyYEh9A050YzT" %} [Stats](/metrics-api-reference/resources/carts/stats.md) {% endcontent-ref %} {% content-ref url="/pages/gv3c3WdhWOlrOf7WXaqI" %} [Search](/metrics-api-reference/resources/carts/search.md) {% endcontent-ref %} {% content-ref url="/pages/UtPzIfbmPp7fI7sps6tp" %} [Export](/metrics-api-reference/resources/carts/export.md) {% endcontent-ref %} The results of each query can be filtered based on specific fields and operators: {% content-ref url="/pages/tC9wnOAXm12J8aDi6ysr" %} [Filters](/metrics-api-reference/resources/carts/filters.md) {% endcontent-ref %} You can easily see it in action by checking these simple examples: {% content-ref url="/pages/b42YeUlOZuVnkkDiaxNa" %} [Examples](/metrics-api-reference/resources/carts/examples.md) {% endcontent-ref %} {% hint style="warning" %} The Metrics API provides the full cart history starting from **August 1st, 2022**. {% endhint %} {% hint style="info" %} If you need to do statistics on *real orders* (i.e. *placed*, *approved*, or *cancelled* orders), please use the `/orders` endpoint (read more [here](/metrics-api-reference/resources/orders.md)). {% endhint %} ## Fields and attributes Please reference to this list for a comprehensive view of all the cart 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. | #### `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. | | **`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. | | **`payment_status`** | String | The order's payment status. Always `unpaid` for carts. | | **`fulfillment_status`** | String | The order's fulfillment status. Aways `unfulfilled` for carts. | | **`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`. | | **`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). | | **`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. | | **`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). | | **`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 `draft` (default), `pending`. | | **`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). | | **`aggregated_details`** | String | Searchable field containing all carts 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). | #### `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. | #### `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). | --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.commercelayer.io/metrics-api-reference/resources/carts.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.