# Carts Within Commerce Layer, every order that's not yet placed acts as a shopping cart. [Orders](https://app.gitbook.com/s/RWJeylueWkzLadK710XZ/orders) 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="carts/breakdown" %} [breakdown](https://docs.commercelayer.io/metrics-api-reference/resources/carts/breakdown) {% endcontent-ref %} {% content-ref url="carts/date-breakdown" %} [date-breakdown](https://docs.commercelayer.io/metrics-api-reference/resources/carts/date-breakdown) {% endcontent-ref %} {% content-ref url="carts/stats" %} [stats](https://docs.commercelayer.io/metrics-api-reference/resources/carts/stats) {% endcontent-ref %} {% content-ref url="carts/search" %} [search](https://docs.commercelayer.io/metrics-api-reference/resources/carts/search) {% endcontent-ref %} {% content-ref url="carts/export" %} [export](https://docs.commercelayer.io/metrics-api-reference/resources/carts/export) {% endcontent-ref %} The results of each query can be filtered based on specific fields and operators: {% content-ref url="carts/filters" %} [filters](https://docs.commercelayer.io/metrics-api-reference/resources/carts/filters) {% endcontent-ref %} You can easily see it in action by checking these simple examples: {% content-ref url="carts/examples" %} [examples](https://docs.commercelayer.io/metrics-api-reference/resources/carts/examples) {% 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](https://docs.commercelayer.io/metrics-api-reference/resources/orders)). {% 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). |