Mirakl Returns API
The Returns API from Mirakl — 8 operation(s) for returns.
OpenAPI Specification
openapi: 3.1.0
info:
description: '{% partial file="/partial-content/product/connect-channel-platform/rest/connect/openapi-description.md" /%}'
title: Mirakl Connect Channel Platform APIs Carriers Returns API
version: ''
servers:
- description: Connect Channel Platform API
url: https://miraklconnect.com/api/channel-platform
tags:
- name: Returns
paths:
/v1/orders/returns:
post:
description: "<div class=\"extension-title\">Description</div>\n\nUse this API to synchronize returns with Mirakl Connect.\n\n ## Overview\n - Returns are always associated to an order already known by Mirakl Connect\n - Each return line must reference an order line already known by Mirakl Connect\n - The API performs an upsert: existing returns are updated, new ones are created\n - The operation is **partially successful**: some returns in the payload can succeed while others fail\n\n ## Usage Notes\n - The `channel_order_id` must reference an order previously synchronized through the orders API\n - Each `channel_order_line_id` in `return_lines` must reference an order line previously synchronized through the orders API\n - This API does not support PATCH operations. Always send all fields for each return.\n - When the request is syntactically valid, HTTP status is `200` even if some or all returns failed\n - Global failures are reported with standard HTTP errors: `400` for invalid payloads and `404` for unknown global resources (such as channel or store).\n\n\n<div class=\"api-description-extension\">\n<div class=\"extension-title\">Call Frequency</div>\n\n<div class=\"recommended-call-frequency\">Recommended usage: Every 5 minutes</div>\n<div class=\"max-call-frequency\">Maximum usage: Once per minute</div>\n</div>"
operationId: upsertReturns
requestBody:
content:
application/json:
examples:
application/json-auto:
summary: Complete example with value types (application/json)
value:
origin:
channel_id: string
channel_store_id: string
returns:
- channel_return_id: string
channel_order_id: string
rma_id: string
status: REQUEST_INITIATED
tracking:
tracking_number: string
carrier_name: string
tracking_url: string
label_url: string
method: string
rejection_reason: RETURN_WINDOW_CLOSED
address:
street: string
street_additional_info: string
city: string
state: string
country: string
country_iso_code: string
zip_code: string
created_at: '2023-03-28T09:34:42Z'
channel_updated_at: '2023-03-28T09:34:42Z'
return_lines:
- channel_order_line_id: string
quantity: 0
reason: WRONG_ITEM
sub_channel_code: string
schema:
$ref: '#/components/schemas/UpsertReturnsRequest'
required: true
responses:
'200':
content:
application/json:
examples:
application/json-auto:
summary: Complete example with value types (application/json)
value:
return_success:
- channel_order_id: string
channel_return_id: string
return_errors:
- channel_order_id: string
channel_return_id: string
details:
- code: string
message: string
field: string
schema:
$ref: '#/components/schemas/UpsertReturnsResponse'
description: Detailed per-return upsert result. Response body contains success and error details for each return.
'400':
content:
application/json:
examples:
application/json-auto:
summary: Complete example with value types (application/json)
value:
code: DATA_NOT_FOUND
message: An error occurred while processing your request
errors:
- message: 'An error occurred while processing your request: id is null'
field: input.account.id
extensions:
minLength: 1
maxLength: 255
extensions:
minLength: 1
maxLength: 255
schema:
$ref: '#/components/schemas/Error'
description: Bad Request
'404':
content:
application/json:
examples:
application/json-auto:
summary: Complete example with value types (application/json)
value:
code: DATA_NOT_FOUND
message: An error occurred while processing your request
errors:
- message: 'An error occurred while processing your request: id is null'
field: input.account.id
extensions:
minLength: 1
maxLength: 255
extensions:
minLength: 1
maxLength: 255
schema:
$ref: '#/components/schemas/Error'
description: 'A critical resource was not found. This may occur if: - The channel or its technology is unknown to connect - The store is unknown to connect'
security:
- Bearer:
- connect-channel-platform:order-returns:upsert
summary: upsertReturns - Upsert returns
tags:
- Returns
/api/returns:
post:
description: '<div class="extension-title">Description</div>
Limited to 200 returns at a time
<div class="api-description-extension">
<div class="extension-title">Call Frequency</div>
<div class="recommended-call-frequency">Recommended usage: At each customer return request</div>
<div class="max-call-frequency">Maximum usage: At each customer return request</div>
<div class="extension-title">Read More</div>
<ul><li><a href="https://help.mirakl.com/bundle/customers/page/topics/Mirakl/concepts/Order/return-concept.htm">More context</a></li></ul></div>'
operationId: RT01
parameters: []
requestBody:
content:
application/json:
examples:
application/json-0:
summary: Example with business values (application/json)
value:
returns:
- accepted: null
label_url: https://www.label-url.com
method_code: RETURN_METHOD_BY_MAIL
order_commercial_id: ORDER-001
reason_code: RETURN_CHANGED_MIND
return_lines:
- order_line_id: ORDER-001-A-1
quantity: 1
- order_line_id: ORDER-001-B-2
quantity: 2
rma: RETURN_RMA
- accepted: true
description: Description of return
label_url: null
method_code: RETURN_METHOD_DROP_OFF_POINT
order_commercial_id: ORDER-DROPSHIP-1
reason_code: RETURN_CHANGED_MIND
return_lines:
- order_line_id: ORDER-DROPSHIP-1-A-1
quantity: 1
rma: null
application/json-auto:
summary: Complete example with value types (application/json)
value:
returns:
- accepted: true
description: string
label_url: string
method_code: RETURN_METHOD_BY_MAIL
order_commercial_id: string
reason_code: RETURN_BROKEN_ITEM
return_lines:
- order_line_id: string
quantity: 0
reason_code: string
rma: string
schema:
$ref: '#/components/schemas/RT01_Request'
responses:
'200':
content:
application/json:
examples:
application/json-0:
summary: Example with business values (application/json)
value:
return_errors:
- message: The returns are not enabled for the platform model of the order line ORDER-DROPSHIP-1-A-1
order_commercial_id: ORDER-DROPSHIP-1
return_success:
- date_created: '2022-09-28T13:37:00Z'
description: Description of return
documents: []
id: ef0e41b6-35ed-4103-86a1-0e33d50a6b05
label_url: https://www.label-url.com
last_updated: '2022-09-28T13:37:00Z'
method_code: RETURN_METHOD_BY_MAIL
order_commercial_id: ORDER-001
order_id: ORDER-001-A
reason_code: RETURN_CHANGED_MIND
rejection_reason_code: null
return_address:
city: New York
country_iso_code: USA
state: Manhattan
street1: 30, Prince Street
street2: 1st floor
zip_code: NY 10012
return_lines:
- compliance: null
order_line_id: ORDER-001-A-1
quantity: 1
rma: RETURN_RMA
status: WAITING_ACCEPTANCE
tracking: null
- date_created: '2022-09-28T13:37:00Z'
documents: []
id: ef0e41b6-35ed-4103-86a1-0e33d50a6b05
label_url: null
last_updated: '2022-09-28T13:37:00Z'
method_code: RETURN_METHOD_BY_MAIL
order_commercial_id: ORDER-001
order_id: ORDER-001-B
reason_code: RETURN_CHANGED_MIND
rejection_reason_code: null
return_address:
city: New York
country_iso_code: USA
state: Manhattan
street1: 30, Prince Street
street2: 1st floor
zip_code: NY 10012
return_lines:
- compliance: null
order_line_id: ORDER-001-B-2
quantity: 2
rma: null
status: WAITING_ACCEPTANCE
tracking: null
application/json-auto:
summary: Complete example with value types (application/json)
value:
return_errors:
- message: string
order_commercial_id: string
return_success:
- date_created: '2023-03-28T09:34:42Z'
description: string
documents:
- id: 0
type: string
id: string
label_url: string
last_updated: '2023-03-28T09:34:42Z'
method_code: RETURN_METHOD_BY_MAIL
order_commercial_id: string
order_id: string
reason_code: RETURN_BROKEN_ITEM
rejection_reason_code: RETURN_REJECTION_NOT_ELIGIBLE
return_address:
city: string
country_iso_code: string
state: string
street1: string
street2: string
zip_code: string
return_lines:
- compliance:
- compliant: true
non_compliance_additional_info: string
non_compliance_reason_code: string
order_line_id: string
quantity: 0
reason_code: RETURN_BROKEN_ITEM
rma: string
state: WAITING_ACCEPTANCE
tracking:
carrier_code: string
carrier_name: string
carrier_standard_code: string
tracking_number: string
tracking_url: string
schema:
type: object
$ref: '#/components/schemas/RT01_Response_200'
description: OK
security:
- Operator-Bearer-Token: []
- OAuth-2: []
summary: RT01 - Create returns
tags:
- Returns
put:
description: '<div class="api-description-extension">
<div class="extension-title">Read More</div>
<ul><li><a href="https://help.mirakl.com/bundle/customers/page/topics/Mirakl/concepts/Order/return-concept.htm">More context</a></li></ul></div>'
operationId: RT04
parameters: []
requestBody:
content:
application/json:
examples:
application/json-0:
summary: Example with business values (application/json)
value:
returns:
- id: f61b5db8-d8f5-4715-b05f-aa4432c0e9e2
tracking:
tracking_url: https://www.tracking.com
- id: c91b5db8-d8f5-4715-b05f-aa4432c0e989
tracking:
tracking_url: https://invalid_url
- id: 2dc4f7d7
tracking:
tracking_url: https://www.tracking.com
- id: 21456f96-19ef-4f34-97be-6cf937755f01
rma: RETURN_RMA
- id: 2dc4f7d7-da59-4588-bec7-ce62daab2f93
label_url: https://www.label-url.com
rma: RETURN_RMA
tracking:
carrier_name: customCarrier
tracking_number: 1H79D0K76
tracking_url: https://www.tracking.com
- id: 1716be7a-93f0-4242-b55b-fff05a76d168
label_url: https://www.label-url.com
rma: RETURN_RMA
tracking:
carrier_code: UPS
tracking_number: 6HD869420
application/json-auto:
summary: Complete example with value types (application/json)
value:
returns:
- id: string
label_url: string
method_code: RETURN_METHOD_BY_MAIL
return_address:
address:
city: string
country_iso_code: AFG
state: string
street1: string
street2: string
zip_code: string
rma: string
tracking:
carrier_code: string
carrier_name: string
carrier_standard_code: string
tracking_number: string
tracking_url: string
schema:
$ref: '#/components/schemas/RT04_Request'
responses:
'200':
content:
application/json:
examples:
application/json-0:
summary: Example with business values (application/json)
value:
return_errors:
- id: f61b5db8-d8f5-4715-b05f-aa4432c0e9e2
message: Return is in invalid state
- id: c91b5db8-d8f5-4715-b05f-aa4432c0e989
message: Invalid return tracking URL format
- id: 21456f96-19ef-4f34-97be-6cf937755f01
message: Order is in invalid state
- id: 2dc4f7d7
message: The return id is incorrect.
return_success:
- date_created: '2023-02-27T16:32:52Z'
description: Description of return
documents: []
id: 2dc4f7d7-da59-4588-bec7-ce62daab2f93
label_url: https://www.label-url.com
last_updated: '2023-02-27T16:37:19Z'
method_code: RETURN_METHOD_DROP_OFF
order_commercial_id: ORDER-2
order_id: ORDER-2-A
reason_code: RETURN_COUNTERFEIT_ITEM
rejection_reason_code: RETURN_REJECTION_NOT_ELIGIBLE
return_address:
city: New York
country_iso_code: USA
state: Manhattan
street1: 30, Prince Street
street2: 1st floor
zip_code: NY 10012
return_lines:
- compliance:
- compliant: false
non_compliance_additional_info: There is a missing item
non_compliance_reason_code: RETURN_NON_COMPLIANT_MISSING_ITEM
order_line_id: ORDER-2-A-1
quantity: 1
rma: RETURN_RMA
state: REFUSED
tracking:
carrier_code: null
carrier_name: newCarrier
carrier_standard_code: null
tracking_number: 1H79D0K76
tracking_url: https://www.tracking.com
- date_created: '2023-04-18T15:24:51Z'
documents: []
id: 1716be7a-93f0-4242-b55b-fff05a76d168
label_url: https://www.label-url.com
last_updated: '2023-05-27T16:37:19Z'
method_code: RETURN_METHOD_DROP_OFF
order_commercial_id: ORDER-2
order_id: ORDER-2-A
reason_code: RETURN_COUNTERFEIT_ITEM
rejection_reason_code: RETURN_REJECTION_NOT_ELIGIBLE
return_address:
city: New York
country_iso_code: USA
state: Manhattan
street1: 30, Prince Street
street2: 1st floor
zip_code: NY 10012
return_lines:
- compliance:
- compliant: false
non_compliance_additional_info: There is a missing item
non_compliance_reason_code: RETURN_NON_COMPLIANT_MISSING_ITEM
order_line_id: ORDER-2-A-1
quantity: 1
rma: RETURN_RMA
state: REFUSED
tracking:
carrier_code: UPS
carrier_name: UPS
carrier_standard_code: ups
tracking_number: 6HD869420
tracking_url: https://wwwapps.ups.com/WebTracking/track?track=yes&trackNums=6HD869420
application/json-auto:
summary: Complete example with value types (application/json)
value:
return_errors:
- id: string
message: string
return_success:
- date_created: '2023-03-28T09:34:42Z'
description: string
documents:
- id: 0
type: string
id: string
label_url: string
last_updated: '2023-03-28T09:34:42Z'
method_code: RETURN_METHOD_BY_MAIL
order_commercial_id: string
order_id: string
reason_code: RETURN_BROKEN_ITEM
rejection_reason_code: RETURN_REJECTION_NOT_ELIGIBLE
return_address:
city: string
country_iso_code: string
state: string
street1: string
street2: string
zip_code: string
return_lines:
- compliance:
- compliant: true
non_compliance_additional_info: string
non_compliance_reason_code: string
order_line_id: string
quantity: 0
reason_code: RETURN_BROKEN_ITEM
rma: string
state: WAITING_ACCEPTANCE
tracking:
carrier_code: string
carrier_name: string
carrier_standard_code: string
tracking_number: string
tracking_url: string
schema:
type: object
$ref: '#/components/schemas/RT04_Response_200'
description: OK
security:
- Operator-Bearer-Token: []
- OAuth-2: []
summary: RT04 - Patch update returns
tags:
- Returns
get:
description: '<div class="api-description-extension">
<div class="extension-title">Call Frequency</div>
<div class="recommended-call-frequency">Recommended usage: Every 15 minutes</div>
<div class="max-call-frequency">Maximum usage: Every 5 minutes</div>
<div class="extension-title">Read More</div>
<ul><li><a href="https://help.mirakl.com/bundle/customers/page/topics/Mirakl/concepts/Order/return-concept.htm">More context</a></li></ul><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>date_created</b> (Default) - Sort by return date creation (asc by default)</li></ul>
</div>'
operationId: RT11
parameters:
- description: Return id for filtering. This parameter can be supplied multiple times (return_id=58fd00d1-4ea4-453e-9a56-ec28c5c156ea&return_id=3071c162-dcd9-414b-a39d-ac3165f29453...).
explode: true
in: query
name: return_id
required: false
schema:
type: array
items:
type: string
style: form
- description: Return state for filtering. This parameter can be supplied multiple times (return_state=WAITING_ACCEPTANCE&return_state=IN_PROGRESS...).
explode: true
in: query
name: return_state
required: false
schema:
type: array
items:
type: string
style: form
- description: Filter returns with a creation date after the given date.
explode: true
in: query
name: return_creation_date_from
required: false
schema:
type: string
format: date-time
style: form
- description: Filter returns with a creation date before the given date.
explode: true
in: query
name: return_creation_date_to
required: false
schema:
type: string
format: date-time
style: form
- description: Filter returns updated after the given date.
explode: true
in: query
name: return_last_updated_from
required: false
schema:
type: string
format: date-time
style: form
- description: Filter returns updated before the given date.
explode: true
in: query
name: return_last_updated_to
required: false
schema:
type: string
format: date-time
style: form
- description: Order commercial id for filtering. This parameter can be supplied multiple times (order_commercial_id=OR01-A&order_commercial_id=OR02-A...).
explode: true
in: query
name: order_commercial_id
required: false
schema:
type: array
items:
type: string
style: form
- description: Order line id for filtering. This parameter can be supplied multiple times (order_line_id=OR01-A-1&order_line_id=OR02-A-1...).
explode: true
in: query
name: order_line_id
required: false
schema:
type: array
items:
type: string
style: form
- description: Return RMA for filtering. This parameter can be supplied multiple times (return_rma=RMA-1&return_rma=RMA-2...).
explode: true
in: query
name: return_rma
required: false
schema:
type: array
items:
type: string
style: form
- description: Customer id for filtering. This parameter can be supplied multiple times (customer_id=id1&customer_id=id2...).
explode: true
in: query
name: customer_id
required: false
schema:
type: array
items:
type: string
style: form
responses:
'200':
content:
application/json:
examples:
application/json-0:
summary: Example with business values (application/json)
value:
data:
- date_created: '2023-02-27T16:14:52Z'
description: Description of return
documents:
- id: 1337
type: SYSTEM_RETURN_LABEL
id: f61b5db8-d8f5-4715-b05f-aa4432c0e9e2
label_url: null
last_updated: '2023-02-27T16:14:52Z'
method_code: RETURN_METHOD_BY_MAIL
order_commercial_id: ORDER-1
order_id: ORDER-1-A
reason_code: RETURN_CHANGED_MIND
rejection_reason_code: null
return_address:
city: New York
country_iso_code: USA
state: Manhattan
street1: 30, Prince Street
street2: 1st floor
zip_code: NY 10012
return_lines:
- compliance:
- compliant: false
non_compliance_additional_info: There is a missing item
non_compliance_reason_code: RETURN_NON_COMPLIANT_MISSING_ITEM
order_line_id: ORDER-1-A-1
quantity: 2
- compliance: null
order_line_id: ORDER-1-A-2
quantity: 3
rma: RETURN_RMA
state: WAITING_ACCEPTANCE
tracking:
carrierCode: UPS
carrierName: UPS
carrier_standard_code: ups
tracking_number: 35H8O95K
tracking_url: https://wwwapps.ups.com/WebTracking/track?track=yes&trackNums=35H8O95K
- date_created: '2023-02-27T16:32:52Z'
documents: []
id: 2dc4f7d7-da59-4588-bec7-ce62daab2f93
label_url: https://www.label-url.com
last_updated: '2023-02-27T16:37:19Z'
method_code: RETURN_METHOD_DROP_OFF
order_commercial_id: ORDER-2
order_id: ORDER-2-A
reason_code: RETURN_COUNTERFEIT_ITEM
rejection_reason_code: RETURN_REJECTION_NOT_ELIGIBLE
return_address:
city: New York
country_iso_code: USA
state: Manhattan
street1: 30, Prince Street
street2: 1st floor
zip_code: NY 10012
return_lines:
- compliance:
- compliant: true
non_compliance_additional_info: null
non_compliance_reason_code: null
order_line_id: ORDER-2-A-1
quantity: 1
rma: null
state: REFUSED
tracking: null
next_page_token: dGhpcy1pcy1hLWZha2UtcGFnZS10b2tlbi1wbGVhc2UtcmVseS1vbi10aGUtdG9rZW4tcHJvdmlkZWQtYnktdGhlLWFwaS1yZXNwb25zZQo=
previous_page_token: null
application/json-auto:
summary: Complete example with value types (application/json)
value:
data:
- date_created: '2023-03-28T09:34:42Z'
description: string
documents:
- id: 0
type: string
id: string
label_url: string
last_updated: '2023-03-28T09:34:42Z'
method_code: RETURN_METHOD_BY_MAIL
order_commercial_id: string
order_id: string
reason_code: RETURN_BROKEN_ITEM
rejection_reason_code: RETURN_REJECTION_NOT_ELIGIBLE
return_address:
city: string
country_iso_code: string
state: string
street1: string
street2: string
zip_code: string
return_lines:
- compliance:
- compliant: true
non_compliance_additional_info: string
non_compliance_reason_code: string
order_line_id: string
quantity: 0
reason_code: RETURN_BROKEN_ITEM
rma: string
state: WAITING_ACCEPTANCE
tracking:
carrier_code: string
carrier_name: string
carrier_standard_code: string
tracking_number: string
tracking_url: string
next_page_token: string
previous_page_token: string
schema:
type: object
$ref: '#/components/schemas/RT11_Response_200'
description: OK
security:
- Operator-Bearer-Token: []
- OAuth-2: []
summary: RT11 - List returns
tags:
- Returns
/api/returns/items_to_return:
get:
description: '<div class="api-description-extension">
<div class="extension-title">Call Frequency</div>
<div class="recommended-call-frequency">Recommended usage: At each custome
# --- truncated at 32 KB (92 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/mirakl/refs/heads/main/openapi/mirakl-returns-api-openapi.yml