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:

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

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

AttributeTypeDescription

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.

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

AttributeTypeDescription

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

AttributeTypeDescription

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

AttributeTypeDescription

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

AttributeTypeDescription

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

AttributeTypeDescription

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

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

aggregated_details

String

Searchable field containing all orders data.

payment_method field

AttributeTypeDescription

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

AttributeTypeDescription

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

AttributeTypeDescription

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.

shipments field

AttributeTypeDescription

id

String

The shipment ID.

number

String

The shipment number.

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

Shipment stock_location field

AttributeTypeDescription

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

AttributeTypeDescription

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 standard), automatically inherited from the order's market.

Shipment shipping_category field

AttributeTypeDescription

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

AttributeTypeDescription

id

String

The tag ID.

name

String

The tag name.

tags field

AttributeTypeDescription

id

String

The tag ID.

name

String

The tag name.

Last updated