Carts

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

Within Commerce Layer, every order that's not yet placed acts as a shopping cart. 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 queries on the /carts/{{query_type}} endpoint to gather stats and information about your organization cart history:

BreakdownDate breakdownStatsSearch

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

The Metrics API provides the full cart history starting from August 1st, 2022.

If you need to do statistics on real orders (i.e. placed, approved, or cancelled orders), please use the /orders endpoint (read more here).

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 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.
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.
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 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.
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).
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 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).
aggregated_details	String	Searchable field containing all carts data.

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 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.