Mirakl Returns API

openapi: 3.2.0
info:
  title: Mirakl Returns API
  version: ''
  description: 'Operations tagged Returns across 5 of this provider''s published API definitions: mirakl-connect-channel-openapi.json, mirakl-connect-openapi.yaml, mirakl-mmp-front-openapi.yaml, mirakl-mmp-operator-openapi.json, mirakl-mmp-seller-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- description: Connect Channel Platform API
  url: https://miraklconnect.com/api/channel-platform
- description: Connect Production endpoint
  url: https://miraklconnect.com/api
- description: URL to be replaced by your Mirakl instance URL
  url: https://your-instance.mirakl.net
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
    servers:
    - description: Connect Channel Platform API
      url: https://miraklconnect.com/api/channel-platform
  /v2/orders/returns/{return_id}/accept:
    put:
      description: '<div class="extension-title">Description</div>


        Use this API to accept or refuse a return that is in the <code>REQUEST_INITIATED</code> status, from Mirakl Connect. The API also synchronizes the return status on the sales channel.


        <div class="api-description-extension">

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


        <div class="recommended-call-frequency">Recommended usage: On each new return</div>

        <div class="max-call-frequency">Maximum usage: On each new return</div>

        </div>'
      operationId: v2-acceptReturn
      parameters:
      - description: Return identifier in Mirakl Connect
        example: 70885
        explode: false
        in: path
        name: return_id
        required: true
        schema:
          type: string
        style: simple
      requestBody:
        content:
          application/json:
            examples:
              application/json-0:
                summary: Accept return request
                value:
                  accepted: true
              application/json-1:
                summary: Refuse return request
                value:
                  accepted: false
                  rejection_reason: NOT_ELIGIBLE_FOR_RETURN
              application/json-auto:
                summary: Complete example with value types (application/json)
                value:
                  accepted: true
                  rejection_reason: RETURN_WINDOW_CLOSED
            schema:
              $ref: '#/components/schemas/AcceptReturnRequest'
        required: true
      responses:
        '202':
          content:
            application/json:
              examples:
                application/json-0:
                  summary: Accepted Response
                  value:
                    action_id: 1ba5fc4b-c4fd-4251-880b-3052e301bbd4
                    tracking_id: 1ba5fc4b-c4fd-4251-880b-3052e301bbd4
                application/json-auto:
                  summary: Complete example with value types (application/json)
                  value:
                    action_id: 1ba5fc4b-c4fd-4251-880b-3052e301bbd4
                    tracking_id: 1ba5fc4b-c4fd-4251-880b-3052e301bbd4
              schema:
                $ref: '#/components/schemas/AsynchronousActionResponse'
          description: Accepted. The accept request will be processed asynchronously.
        '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: The return status has not been updated because of wrong or missing parameters.
        '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: The return status has not been updated because the return does not exist.
      security:
      - Bearer:
        - connect:order-return:accept
      summary: v2-acceptReturn - Accept or refuse return
      tags:
      - Returns
    servers:
    - description: Connect Production endpoint
      url: https://miraklconnect.com/api
  /v2/orders/returns/{return_id}/receive:
    put:
      description: '> ⚠️ **Content-length header**

        >

        > The Content-Length header must be present with value 0, even when there is no request body.


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


        Use this API to marks the return as received to officially confirm physical reception of the item from the customer. The API also synchronizes the return status on the sales channel.


        <div class="api-description-extension">

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


        <div class="recommended-call-frequency">Recommended usage: On each new return</div>

        <div class="max-call-frequency">Maximum usage: On each new return</div>

        </div>'
      operationId: v2-acknowledgeReturnReception
      parameters:
      - description: Return identifier in Mirakl Connect
        example: 70885
        explode: false
        in: path
        name: return_id
        required: true
        schema:
          type: string
        style: simple
      responses:
        '202':
          content:
            application/json:
              examples:
                application/json-0:
                  summary: Acknowledge return reception response
                  value:
                    action_id: 1ba5fc4b-c4fd-4251-880b-3052e301bbd4
                    tracking_id: 1ba5fc4b-c4fd-4251-880b-3052e301bbd4
                application/json-auto:
                  summary: Complete example with value types (application/json)
                  value:
                    action_id: 1ba5fc4b-c4fd-4251-880b-3052e301bbd4
                    tracking_id: 1ba5fc4b-c4fd-4251-880b-3052e301bbd4
              schema:
                $ref: '#/components/schemas/AsynchronousActionResponse'
          description: Accepted. The accept request will be processed asynchronously.
        '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: The return status has not been updated because of wrong or missing parameters.
        '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: The return status has not been updated because the return does not exist.
      security:
      - Bearer:
        - connect:order-return:receive
      summary: v2-acknowledgeReturnReception - Mark return as received
      tags:
      - Returns
    servers:
    - description: Connect Production endpoint
      url: https://miraklconnect.com/api
  /v2/orders/returns/{return_id}/close:
    put:
      description: '> ⚠️ **Content-length header**

        >

        > The Content-Length header must be present with value 0, even when there is no request body.


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


        Use this API to marks the return as closed after all necessary steps required by the marketplace or seller’s process are completed (e.g., refund, compliance check, restocking). The API also synchronizes the return status on the sales channel.


        <div class="api-description-extension">

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


        <div class="recommended-call-frequency">Recommended usage: On each new return</div>

        <div class="max-call-frequency">Maximum usage: On each new return</div>

        </div>'
      operationId: v2-closeReturn
      parameters:
      - description: Return identifier in Mirakl Connect
        example: 70885
        explode: false
        in: path
        name: return_id
        required: true
        schema:
          type: string
        style: simple
      responses:
        '202':
          content:
            application/json:
              examples:
                application/json-0:
                  summary: Close return response
                  value:
                    action_id: 1ba5fc4b-c4fd-4251-880b-3052e301bbd4
                    tracking_id: 1ba5fc4b-c4fd-4251-880b-3052e301bbd4
                application/json-auto:
                  summary: Complete example with value types (application/json)
                  value:
                    action_id: 1ba5fc4b-c4fd-4251-880b-3052e301bbd4
                    tracking_id: 1ba5fc4b-c4fd-4251-880b-3052e301bbd4
              schema:
                $ref: '#/components/schemas/AsynchronousActionResponse'
          description: Accepted. The accept request will be processed asynchronously.
        '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: The return status has not been updated because of wrong or missing parameters.
        '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: The return status has not been updated because the return does not exist.
      security:
      - Bearer:
        - connect:order-return:close
      summary: v2-closeReturn - Mark return as closed
      tags:
      - Returns
    servers:
    - description: Connect Production endpoint
      url: https://miraklconnect.com/api
  /v2/orders/returns:
    get:
      description: '<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>'
      operationId: v2-listReturns
      parameters:
      - description: Filter by Connect order identifiers
        explode: true
        in: query
        name: order_ids
        required: false
        schema:
          type: array
          items:
            type: string
          maxItems: 100
        style: form
      - description: Filter by return statuses
        explode: true
        in: query
        name: statuses
        required: false
        schema:
          type: array
          items:
            type: string
            enum:
            - REQUEST_INITIATED
            - REQUEST_DECLINED
            - OPENED
            - RECEIVED
            - CLOSED
          maxItems: 100
        style: form
      - description: Select returns that were last updated in Mirakl Connect from the specified date time.
        explode: true
        in: query
        name: updated_from
        required: true
        schema:
          type: string
          format: date-time
          example: '2021-01-01T08:30:00Z'
        style: form
      - description: Token to access the next or previous page
        explode: true
        in: query
        name: page_token
        required: false
        schema:
          type: string
        style: form
      - description: Maximum number of listed returns
        explode: true
        in: query
        name: limit
        required: false
        schema:
          type: integer
          default: 10
          maximum: 100
          minimum: 1
        style: form
      responses:
        '200':
          content:
            application/json:
              examples:
                application/json-0:
                  summary: A page of returns
                  value:
                    data:
                    - address:
                        city: New York
                        country: United States
                        country_iso_code: USA
                        state: NY
                        street: 123 Main St
                        street_additional_info: Apt 4B
                        zip_code: '10001'
                      channel_return_id: '12345'
                      channel_updated_at: '2025-03-06T16:00:00Z'
                      created_at: '2025-03-06T14:55:00Z'
                      id: 70885
                      label_url: https://store.example.com/returns/label/12345
                      method: RETURN_METHOD_IN_STORE
                      order_id: 0002_3202630-A
                      origin:
                        channel_id: '0002'
                        channel_name: Connect MP 2
                        channel_store_id: '4'
                        channel_store_name: '* Super Shop USA'
                        sub_channel_code: EU-FR
                        sub_channel_name: France
                      rejection_reason: RETURN_WINDOW_CLOSED
                      return_lines:
                      - order_line_id: 0002_3202630-A-1
                        product_id: '528216235'
                        quantity: 2
                        reason: DEFECTIVE_ITEM
                      rma_id: RMA-12345
                      status: OPENED
                      tracking:
                        carrier_name: CarrierCo
                        tracking_number: TRACK123456789
                        tracking_url: https://carrierco.com/track?num=TRACK123456789
                      updated_at: '2025-03-06T16:00:00Z'
                    next_page_token: bGltaXQ9MTAmYWZ0ZXI9MjAyMS0xMS0xNlQxNjoxNTowOSswMTowMCZhZnRlcj1jb25uZWN0bXAxLXRlc3QmYWZ0ZXI9MzE3ODczOC1BJnNvcnQ9ZGF0ZV91cGRhdGVkLERFU0M=
                    previous_page_token: YmVmb3JlPTIwMjEtMTEtMjRUMDA6MDA6MTErMDE6MDAmYmVmb3JlPWNvbm5lY3RtcDItdGVzdCZiZWZvcmU9MzIwMjYzMC1BJmxpbWl0PTEwJnNvcnQ9ZGF0ZV91cGRhdGVkLERFU0M=
                application/json-auto:
                  summary: Complete example with value types (application/json)
                  value:
                    previous_page_token: string
                    next_page_token: string
                    data:
                    - id: string
                      channel_return_id: string
                      order_id: string
                      origin:
                        channel_id: string
                        channel_name: string
                        channel_store_id: string
                        channel_store_name: string
                        channel_type: AGENTIC
                        sub_channel_code: string
                        sub_channel_name: 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'
                      updated_at: '2023-03-28T09:34:42Z'
                      return_lines:
                      - order_line_id: string
                        quantity: 0
                        reason: WRONG_ITEM
                        product_id: string
              schema:
                $ref: '#/components/schemas/ReturnsPageResponse'
          description: List of returns
      security:
      - Bearer:
        - connect:order-return:read
      summary: v2-listReturns - List Mirakl Connect returns
      tags:
      - Returns
    servers:
    - description: Connect Production endpoint
      url: https://miraklconnect.com/api
  /v2/orders/returns/{return_id}/trackings:
    put:
      description: '<div class="extension-title">Description</div>


        Use this API to update the tracking information of a return from Mirakl Connect. The API also updates the return tracking information on the sales channel.


        <div class="api-description-extension">

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


        <div class="recommended-call-frequency">Recommended usage: On each new return</div>

        <div class="max-call-frequency">Maximum usage: On each new return</div>

        </div>'
      operationId: v2-updateReturnTrackingInformation
      parameters:
      - description: Return identifier in Mirakl Connect
        example: 70885
        explode: false
        in: path
        name: return_id
        required: true
        schema:
          type: string
        style: simple
      requestBody:
        content:
          application/json:
            examples:
              application/json-0:
                summary: Update return tracking information request
                value:
                  label_url: https://shipping.ups.com/returns/labels/d290f1ee-6c54-4b01-90e6-d701748f0851.pdf
                  rma_id: CR117B72FEF5E8391187
                  tracking:
                    carrier: FedEx
                    tracking_number: '791823193211'
                    tracking_url: https://www.fedex.com/fedextrack/?trknbr=791823193211
              application/json-auto:
                summary: Complete example with value types (application/json)
                value:
                  label_url: https://shipping.ups.com/returns/labels/d290f1ee-6c54-4b01-90e6-d701748f0851.pdf
                  rma_id: NL48GEQK22M1-A
                  tracking:
                    tracking_number: '781234567890'
                    tracking_url: https://www.fedex.com/fedextrack/?trknbr=781234567890
                    carrier: DHL Express
            schema:
              $ref: '#/components/schemas/UpdateReturnTrackingInformationRequest'
        required: true
      responses:
        '202':
          content:
            application/json:
              examples:
                application/json-0:
                  summary: Accepted Response
                  value:
                    action_id: 1ba5fc4b-c4fd-4251-880b-3052e301bbd4
                    tracking_id: 1ba5fc4b-c4fd-4251-880b-3052e301bbd4
                application/json-auto:
                  summary: Complete example with value types (application/json)
                  value:
                    action_id: 1ba5fc4b-c4fd-4251-880b-3052e301bbd4
                    tracking_id: 1ba5fc4b-c4fd-4251-880b-3052e301bbd4
              schema:
                $ref: '#/components/schemas/AsynchronousActionResponse'
          description: Accepted. The accept request will be processed asynchronously.
        '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: The return tracking information has not been updated because of wrong or missing parameters.
        '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: The return tracking information has not been updated because the return does not exist.
      security:
      - Bearer:
        - connect:order-return:update-tracking-information
      summary: v2-updateReturnTrackingInformation - Update return tracking information
      tags:
      - Returns
    servers:
    - description: Connect Production endpoint
      url: https://miraklconnect.com/api
  /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
                      quant

# --- truncated at 32 KB (147 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/mirakl/refs/heads/main/openapi/mirakl-returns-api-openapi.yml