# Returns [Returns](/core-api-reference/returns.md) are linked to one specific order. Commerce Layer Metrics API lets you perform different types of queries on the `/returns/{{query_type}}` endpoint to gather stats and information about your organization return history: {% content-ref url="/pages/uxmA3nwBfsilrcGjTVda" %} [Breakdown](/metrics-api-reference/resources/returns/breakdown.md) {% endcontent-ref %} {% content-ref url="/pages/fS9NjvnLPhcrco2dNthQ" %} [Date breakdown](/metrics-api-reference/resources/returns/date-breakdown.md) {% endcontent-ref %} {% content-ref url="/pages/W3qOjXLzLkx03MXC7CYV" %} [Stats](/metrics-api-reference/resources/returns/stats.md) {% endcontent-ref %} {% content-ref url="/pages/SlXWLO2SP3lFr7Rip9DH" %} [Search](/metrics-api-reference/resources/returns/search.md) {% endcontent-ref %} {% content-ref url="/pages/UuBAlU1xhHOWsB5bNq5q" %} [Export](/metrics-api-reference/resources/returns/export.md) {% endcontent-ref %} The results of each query can be filtered based on specific fields and operators: {% content-ref url="/pages/AUGy97YRmbbTlLPd03RT" %} [Filters](/metrics-api-reference/resources/returns/filters.md) {% endcontent-ref %} You can easily see it in action by checking these simple examples: {% content-ref url="/pages/XY2eEuBf1krSEQPB2bY9" %} [Examples](/metrics-api-reference/resources/returns/examples.md) {% endcontent-ref %} ## 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](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. | #### `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](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. | #### `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](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 returns (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. `requested_at`, `rejected_at`, etc.) where to apply the date and time range filter. | | **`aggregated_details`** | String | Searchable field containing all returns data. | | **`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](https://www.w3.org/TR/NOTE-datetime) 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](https://www.w3.org/TR/NOTE-datetime) standard). | | **`archived`** | Boolean | Indicates if the return has been archived. | | **`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](https://www.w3.org/TR/NOTE-datetime) 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](https://www.w3.org/TR/NOTE-datetime) 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](https://www.w3.org/TR/NOTE-datetime) 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](https://www.w3.org/TR/NOTE-datetime) 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](https://www.w3.org/TR/NOTE-datetime) 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](https://www.w3.org/TR/NOTE-datetime) 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](https://www.w3.org/TR/NOTE-datetime) 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. | | **`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 associated market. | #### `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](https://www.w3.org/TR/NOTE-datetime) 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](https://www.w3.org/TR/NOTE-datetime) 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](https://www.w3.org/TR/NOTE-datetime) standard). | | **`line_item_id`** | String | The ID of the return line item. | | **`line_item_name`** | String | The name of the associated SKU or bundle. | | **`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](https://www.w3.org/TR/NOTE-datetime) 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 | Any identifier of the 3rd-party system that defines the reference code. | #### `tags` field | Attribute | Type | Description | | ---------- | ------ | ------------- | | **`id`** | String | The tag ID. | | **`name`** | String | The tag name. | --- # 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/returns.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.