---
title: "v2-listReturns - List Mirakl Connect returns"
method: GET
path: "/v2/orders/returns"
tags: ["Returns"]
---

# v2-listReturns - List Mirakl Connect returns

`GET /v2/orders/returns`

<div class="extension-title">Description</div>

Use this API to synchronize Mirakl Connect returns with your system. We recommend integrating this API in asynchronous mode. You can retrieve all returns updated since the last call, and update your referential accordingly. To do so, schedule a task that calls this API using the <code>updated_from</code> parameter valued with the last execution time of the task.

<div class="api-description-extension">
<div class="extension-title">Call Frequency</div>

<div class="recommended-call-frequency">Recommended usage: Asynchronous: every 5 minutes</div>
<div class="max-call-frequency">Maximum usage: Asynchronous: once per minute</div>
<div class="extension-title">Pagination</div>

<p>This resource supports seek pagination (<a href="#section/Seek-pagination-and-sort">see documentation</a>)</p>

<div class="extension-title">Sort fields</div>

<code>sort</code> field can have the following values:<ul><li><b>updated_at</b> (Default) - Sort by date time of last return modification in Mirakl Connect (desc by default)</li></ul>

</div>

## Query parameters

- `order_ids` string[]
- `statuses` string[]
- `updated_from` string, date-time, required
- `page_token` string
- `limit` integer

## Response `200`

List of returns

- ReturnsPageResponse
  - `next_page_token` string — Token to access the next page. Absent if the current page is the last one.
  - `previous_page_token` string — Token to access the previous page. Absent if the current page is the first one.
  - `data` ReturnResponse[], required — Page of returns corresponding to the filter parameters
    - `address` object
      - `city` string, required — City
      - `country` string — Country
      - `country_iso_code` string, iso-3166-1 alpha-3, required — Country ISO code
      - `state` string — State
      - `street` string, required — Street information
      - `street_additional_info` string — Additional street information
      - `zip_code` string — Postal code
    - `channel_return_id` string, required — Return identifier on the sales channel. This identifier is not guaranteed to be unique as multiple channels can use the same identifier.
    - `channel_updated_at` string, date-time, required — Date time the return was last updated on the sales channel
    - `created_at` string, date-time, required — Date time the return was created on the sales channel
    - `id` string, required — Unique return identifier used by Mirakl Connect. This identifier can be used as a primary key, but it must not be shared with final users.
    - `label_url` string — URL for the return shipping label
    - `method` string — Shipping method name on the sales channel
    - `order_id` string, required — Order identifier used by Mirakl Connect
    - `origin` Origin, required
      - `channel_id` string, required — Unique identifier of the sales channel
      - `channel_name` string — Name of the sales channel
      - `channel_store_id` string — Store identifier on the sales channel. This identifier is not guaranteed to be unique as multiple channels can use the same identifier.
      - `channel_store_name` string — Store public name on the sales channel
      - `sub_channel_code` string — Code of the sub-channel
      - `sub_channel_name` string — Name of the sub-channel
    - `rejection_reason` string — Reason for the return rejection Enum: `"RETURN_WINDOW_CLOSED"`, `"NOT_ELIGIBLE_FOR_RETURN"`, `"FINAL_SALES"`, `"OTHER"`
    - `return_lines` ReturnLineResponse[], required
      - `order_line_id` string, required — Order line identifier used by Mirakl Connect
      - `product_id` string — Returnable item identifier
      - `quantity` integer, required — Quantity of items being returned
      - `reason` string, required — Reason for the return Enum: `"WRONG_ITEM"`, `"MISSING_ITEM"`, `"DEFECTIVE_ITEM"`, `"DAMAGED_ITEM"`, `"UNWANTED_ITEM"`, `"OTHER"`
    - `rma_id` string — Return Merchandise Authorization ID
    - `status` string, required — Current return status Enum: `"REQUEST_INITIATED"`, `"REQUEST_DECLINED"`, `"OPENED"`, `"RECEIVED"`, `"CLOSED"`, `"CHANNEL_SPECIFIC"`
    - `tracking` object
      - `carrier_name` string — Carrier company name
      - `tracking_number` string — Carrier tracking number
      - `tracking_url` string — URL to track the return
    - `updated_at` string, date-time — Date time the return was last updated on Mirakl Connect

---

[API](https://skmtc.net/mirakl/apis/mirakl-connect-apis.md) · [All operations](https://skmtc.net/mirakl/apis/mirakl-connect-apis/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/mirakl/mirakl-connect-apis/revisions/cc009fec5cdd/schema)