Returns

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

​Returns are linked to one specific order. Commerce Layer Metrics API lets you perform different types queries on the /returns/{{query_type}} endpoint to gather stats and information about your organization return history:
Breakdown
Date breakdown
Stats
Search
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 return resource's fields and attributes, accessible through the Metrics API:
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).
destination_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.
origin_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.
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.
return field
Attribute
Type
Description
date_from
String
The lower limit of the date and time range used to filter the collected returns (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 returns (complete date plus hours, minutes and seconds — according to the ISO 8601 standard).
date_field
String
The date field (e.g. requested_at, rejected_at, etc.) where to apply the date and time range filter.
approved_at
String
The date and time at which the return 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 return was archived (complete date plus hours, minutes and seconds — according to the ISO 8601 standard).
cancelled_at
String
The date and time at which the return was cancelled (complete date plus hours, minutes and seconds — according to the ISO 8601 standard).
created_at
String
The date and time at which the return was created (complete date plus hours, minutes and seconds — according to the ISO 8601 standard).
number
String
The numeric unique identifier for the return.
received_at
String
The date and time at which the return was received (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 return 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.
rejected_at
String
The date and time at which the return was rejected (complete date plus hours, minutes and seconds — according to the ISO 8601 standard).
shipped_at
String
The date and time at which the return was shipped (complete date plus hours, minutes and seconds — according to the ISO 8601 standard).
status
String
The return status. One of draft, requested, approved, cancelled, shipped, rejected or received.
updated_at
String
The date and time at which the return 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 return's latest status change, regardless of the return's status (complete date plus hours, minutes and seconds — according to the ISO 8601 standard).
id
String
The ID of the return.
order_id
String
The ID of the order associated with the return.
skus_count
Integer
The total number of SKUs in the return's line items.
return_line_items field
Attribute
Type
Description
created_at
String
The date and time at which the return line item was created (complete date plus hours, minutes and seconds — according to the ISO 8601 standard).
quantity
Integer
The return line item quantity.
restocked_at
String
The date and time at which the return line item was restocked (complete date plus hours, minutes and seconds — according to the ISO 8601 standard).
updated_at
String
The date and time at which the return line item was last updated (complete date plus hours, minutes and seconds — according to the ISO 8601 standard).
line_item_id
String
The ID of the return line item.
line_item_code
String
The code of the associated SKU or bundle.
line_item_item_type
String
The type of the associated item. One of sku, or bundle.
line_item_total_amount
Number
The total amount of the return line item (float).
line_item_tax_amount
Number
The collected tax amount for the return line item (float).
line_item_tax_rate
Number
The tax rate for the return line item (if calculated).
line_item_updated_at
String
The date and time at which the return line item was last updated (complete date plus hours, minutes and seconds — according to the ISO 8601 standard).
stock_location field
Attribute
Type
Description
id
String
The ID of the stock location.
name
String
The name of the stock location.
reference
String
Any external identifier that might be useful to link the stock location resource to other systems through the Commerce Layer core API.
reference_origin
String
​

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

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.

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.

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.

Attribute	Type	Description
`date_from`	String	The lower limit of the date and time range used to filter the collected returns (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 returns (complete date plus hours, minutes and seconds — according to the ISO 8601 standard).
`date_field`	String	The date field (e.g. `requested_at`, `rejected_at`, etc.) where to apply the date and time range filter.
`approved_at`	String	The date and time at which the return 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 return was archived (complete date plus hours, minutes and seconds — according to the ISO 8601 standard).
`cancelled_at`	String	The date and time at which the return was cancelled (complete date plus hours, minutes and seconds — according to the ISO 8601 standard).
`created_at`	String	The date and time at which the return was created (complete date plus hours, minutes and seconds — according to the ISO 8601 standard).
`number`	String	The numeric unique identifier for the return.
`received_at`	String	The date and time at which the return was received (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 return 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.
`rejected_at`	String	The date and time at which the return was rejected (complete date plus hours, minutes and seconds — according to the ISO 8601 standard).
`shipped_at`	String	The date and time at which the return was shipped (complete date plus hours, minutes and seconds — according to the ISO 8601 standard).
`status`	String	The return status. One of `draft`, `requested`, `approved`, `cancelled`, `shipped`, `rejected` or `received`.
`updated_at`	String	The date and time at which the return 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 return's latest status change, regardless of the return's status (complete date plus hours, minutes and seconds — according to the ISO 8601 standard).
`id`	String	The ID of the return.
`order_id`	String	The ID of the order associated with the return.
`skus_count`	Integer	The total number of SKUs in the return's line items.

Attribute	Type	Description
`created_at`	String	The date and time at which the return line item was created (complete date plus hours, minutes and seconds — according to the ISO 8601 standard).
`quantity`	Integer	The return line item quantity.
`restocked_at`	String	The date and time at which the return line item was restocked (complete date plus hours, minutes and seconds — according to the ISO 8601 standard).
`updated_at`	String	The date and time at which the return line item was last updated (complete date plus hours, minutes and seconds — according to the ISO 8601 standard).
`line_item_id`	String	The ID of the return line item.
`line_item_code`	String	The code of the associated SKU or bundle.
`line_item_item_type`	String	The type of the associated item. One of `sku`, or `bundle`.
`line_item_total_amount`	Number	The total amount of the return line item (float).
`line_item_tax_amount`	Number	The collected tax amount for the return line item (float).
`line_item_tax_rate`	Number	The tax rate for the return line item (if calculated).
`line_item_updated_at`	String	The date and time at which the return line item was last updated (complete date plus hours, minutes and seconds — according to the ISO 8601 standard).

Attribute	Type	Description
`id`	String	The ID of the stock location.
`name`	String	The name of the stock location.
`reference`	String	Any external identifier that might be useful to link the stock location resource to other systems through the Commerce Layer core API.
`reference_origin`	String

Examples

Breakdown

Last modified 1mo ago

Returns

Fields and attributes

`customer` field

`destination_address` field

`origin_address` field

`market` field

`return` field

`return_line_items` field

`stock_location` field