Mirakl Orders API

openapi: 3.2.0
info:
  title: Mirakl Orders API
  version: ''
  description: 'Operations tagged Orders across 8 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, mirakl-mms-front-openapi.yaml, mirakl-mms-operator-openapi.json, mirakl-mms-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: Orders
paths:
  /v1/orders/documents/{channel_document_id}:
    delete:
      description: '<div class="extension-title">Description</div>


        Use this API to delete a document.


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

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


        <div class="recommended-call-frequency">Recommended usage: On each document deletion on the order</div>

        <div class="max-call-frequency">Maximum usage: On each document deletion on the order</div>

        </div>'
      operationId: deleteOrderDocument
      parameters:
      - description: Document ID from the channel
        example: DOC-1234
        explode: false
        in: path
        name: channel_document_id
        required: true
        schema:
          type: string
        style: simple
      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
                    sub_channel_code: string
            schema:
              type: object
              properties:
                origin:
                  $ref: '#/components/schemas/DocumentOriginRequest'
              required:
              - origin
        required: true
      responses:
        '204':
          description: No Content
        '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: 'The channel document ID does not exists. This may occur if the ID is incorrect or the document has already been deleted.

            '
      security:
      - Bearer:
        - connect-channel-platform:order-document:delete
      summary: deleteOrderDocument - Delete order document
      tags:
      - Orders
    servers:
    - description: Connect Channel Platform API
      url: https://miraklconnect.com/api/channel-platform
  /v1/orders/actions/{action_id}:
    put:
      description: '<div class="extension-title">Description</div>


        Updates the final status of an asynchronous action previously initiated through a command event.


        ## Overview

        - When an asynchronous action is requested via command event, an `action_id` is provided to track the action

        - Use this endpoint to report the final outcome (SUCCESS or FAILURE) of the action

        - For failed actions, detailed error information must be provided


        ## Usage Notes

        - Update should be sent once the action is fully completed

        - Multiple errors can be provided for failed actions

        - The action ID must match the one provided in the original command event



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

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


        <div class="recommended-call-frequency">Recommended usage: Send update as soon as the action is completed</div>

        <div class="max-call-frequency">Maximum usage: Once per action completion</div>

        </div>'
      operationId: updateActionStatus
      parameters:
      - description: The unique identifier of the action. This ID was provided in the original command event that initiated the action.
        example: 1ba5fc4b-c4fd-4251-880b-3052e301bbd4
        explode: false
        in: path
        name: action_id
        required: true
        schema:
          type: string
        style: simple
      requestBody:
        content:
          application/json:
            examples:
              application/json-auto:
                summary: Complete example with value types (application/json)
                value:
                  status: SUCCESS
                  errors:
                  - code: INVALID_INPUT
                    message: 'Cannot process cancellation: order is already shipped'
            schema:
              $ref: '#/components/schemas/UpdateActionRequest'
        description: The updated status and any error details for the action
        required: true
      responses:
        '204':
          description: The action status was successfully updated. No additional content is provided.
        '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 request was invalid. Common causes include: - Invalid action status : must be either SUCCESS or FAILED - Action is already in a final state (SUCCESS or FAILED). This error will have code `ACTION_ALREADY_FINAL`. - Invalid error format'
        '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 specified action ID was not found. This may occur if: - The ID is incorrect - The action has expired - The action was already completed'
      security:
      - Bearer:
        - connect-channel-platform:order-action:upsert
      summary: updateActionStatus - Update asynchronous action status
      tags:
      - Orders
    servers:
    - description: Connect Channel Platform API
      url: https://miraklconnect.com/api/channel-platform
  /v1/orders/anonymize-after:
    put:
      description: '<div class="extension-title">Description</div>


        Updates the anonymization date for orders in the Mirakl Connect platform.

        Use this API to indicated after which date orders should be anonymized by Connect.

        The anonymization process is irreversible and should be used with caution.



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

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


        <div class="recommended-call-frequency">Recommended usage: Once per order when the anonymization date is set</div>

        <div class="max-call-frequency">Maximum usage: Every time the anonymization date needs to be changed</div>

        </div>'
      operationId: updateAnonymizeAfterDate
      requestBody:
        content:
          application/json:
            examples:
              application/json-auto:
                summary: Complete example with value types (application/json)
                value:
                  orders:
                  - channel_order_id: COMMERCIAL_ID-A
                    channel_id: 1234
                    channel_store_id: string
                    sub_channel_code: string
                    anonymize_after: '2023-10-01T00:00:00Z'
            schema:
              $ref: '#/components/schemas/UpdateAnonymizeAfterRequest'
        description: The new anonymize_after date for the orders
        required: true
      responses:
        '204':
          description: Successfully updated the anonymize_after date for all orders of the request. No additional content is provided.
        '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: 'At least one the item of the payload is invalid. The entire request is canceled, none of the anonymize_after date have been updated. Common errors include: - referencing an order that does not exist - trying to set an anonymize_after date in the past

            Please refer to the error message for more details.'
      security:
      - Bearer:
        - connect-channel-platform:order:update-anonymize-after
      summary: updateAnonymizeAfterDate - Update anonymization date for orders
      tags:
      - Orders
    servers:
    - description: Connect Channel Platform API
      url: https://miraklconnect.com/api/channel-platform
  /v1/orders/{channel_order_id}/documents:
    post:
      description: '<div class="extension-title">Description</div>


        Use this API to upload a document for an order or its related entities (e.g. returns).


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

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


        <div class="recommended-call-frequency">Recommended usage: On each new document on the order</div>

        <div class="max-call-frequency">Maximum usage: On each new document on the order</div>

        </div>'
      operationId: uploadOrderDocument
      parameters:
      - description: Order identifier from the channel
        example: COMMERCIAL_ID-A
        explode: false
        in: path
        name: channel_order_id
        required: true
        schema:
          type: string
        style: simple
      requestBody:
        content:
          multipart/form-data:
            examples:
              multipart/form-data-auto:
                summary: Complete example with value types (multipart/form-data)
                value:
                  file: string
                  origin:
                    channel_id: string
                    channel_store_id: string
                    sub_channel_code: string
                  metadata:
                    channel_document_id: string
                    filename: UPS_1Z999AA10123456784.pdf
                    type: RETURN_LABEL
                    channel_type: string
                    entity:
                      id: caf30673-ea3d-4113-9a18-674850f6a290
                      type: RETURN
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
                  description: "The document file to upload.\n\nMaximum file size: <code>10 MB</code>.\n\nSupported formats are :\n                      - <code>PDF</code>\n                      - <code>JPEG</code>\n                      - <code>PNG</code>\n                      - <code>CSV</code>\n"
                metadata:
                  $ref: '#/components/schemas/UploadOrderDocumentMetadata'
                origin:
                  $ref: '#/components/schemas/DocumentOriginRequest'
              required:
              - file
              - metadata
              - origin
        required: true
      responses:
        '204':
          description: No Content
        '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
      security:
      - Bearer:
        - connect-channel-platform:order-document:upload
      summary: uploadOrderDocument - Upload order document
      tags:
      - Orders
      x-codeSamples:
      - lang: cURL
        source: "curl -i -X POST \\\n  https://miraklconnect.com/api/channel-platform/v1/orders/{channel_order_id}/documents \\\n  -H 'Content-Type: multipart/form-data' \\\n  -F 'file=@path/to/file' \\\n  -F 'origin=\"{\\\"channel_id\\\":\\\"string\\\",\\\"channel_store_id\\\":\\\"string\\\",\\\"sub_channel_code\\\":\\\"string\\\"}\";type=application/json' \\\n  -F 'metadata=\"{\\\"channel_document_id\\\":\\\"string\\\",\\\"filename\\\":\\\"UPS_1Z999AA10123456784.pdf\\\",\\\"type\\\":\\\"RETURN_LABEL\\\",\\\"channel_type\\\":\\\"string\\\",\\\"entity\\\":{\\\"id\\\":\\\"caf30673-ea3d-4113-9a18-674850f6a290\\\",\\\"type\\\":\\\"RETURN\\\"}}\";type=application/json'\n"
    servers:
    - description: Connect Channel Platform API
      url: https://miraklconnect.com/api/channel-platform
  /v1/orders:
    post:
      description: '<div class="extension-title">Description</div>


        Use this API to synchronize orders with Mirakl Connect.


        - The operation is **not partially successful**: if any order in the payload is invalid, the entire request is rejected.

        - This API does not support PATCH operations. All fields must be sent with each upsert request to ensure the complete update of the order data.

        - Updates whose `channel_updated_at` timestamp is older than the value already stored in Connect are silently ignored (anti-replay guard).



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

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


        <div class="recommended-call-frequency">Recommended usage: 20 / sec</div>

        <div class="max-call-frequency">Maximum usage: 30 / sec</div>

        </div>'
      operationId: upsertOrders
      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
                  orders:
                  - channel_order_id: string
                    created_at: '2023-03-28T09:34:42Z'
                    channel_updated_at: '2023-03-28T09:34:42Z'
                    status: AWAITING_ACCEPTANCE
                    shipping_info:
                      email: string
                      address:
                        last_name: string
                        street: string
                        city: string
                        first_name: string
                        company: string
                        street_additional_info: string
                        state: string
                        country: string
                        country_iso_code: string
                        zip_code: string
                        phone: string
                        additional_info: string
                      carrier: string
                      method: string
                      pudo_id: string
                      shipping_deadline: '2023-03-28T09:34:42Z'
                      delivery_date:
                        earliest: '2023-03-28T09:34:42Z'
                        latest: '2023-03-28T09:34:42Z'
                    order_lines:
                    - channel_order_line_id: string
                      created_at: '2023-03-28T09:34:42Z'
                      updated_at: '2023-03-28T09:34:42Z'
                      quantity: 0
                      can_cancel: true
                      can_refund: true
                      total_shipping_price:
                        amount: 0
                        currency: string
                      price:
                        amount: 0
                        currency: string
                      product:
                        id: string
                        title: string
                        thumbnail_url: string
                      taxes:
                      - amount:
                          amount: 0
                          currency: string
                        code: string
                        rate: 0
                        seller_collectible:
                          amount: 0
                          currency: string
                        channel_collectible:
                          amount: 0
                          currency: string
                      shipping_taxes:
                      - amount:
                          amount: 0
                          currency: string
                        code: string
                        rate: 0
                        seller_collectible:
                          amount: 0
                          currency: string
                        channel_collectible:
                          amount: 0
                          currency: string
                      status: AWAITING_ACCEPTANCE
                      status_reason: ACCEPTANCE_TIMEOUT
                      adjustments:
                      - channel_adjustment_id: string
                        reason: CUSTOMER_CANCELATION
                        created_at: '2023-03-28T09:34:42Z'
                        type: REFUND
                        quantity: 0
                        price:
                          amount: 0
                          currency: string
                        taxes:
                        - amount:
                            amount: 0
                            currency: string
                          code: string
                          rate: 0
                          seller_collectible:
                            amount: 0
                            currency: string
                          channel_collectible:
                            amount: 0
                            currency: string
                        shipping_price:
                          amount: 0
                          currency: string
                        shipping_taxes:
                        - amount:
                            amount: 0
                            currency: string
                          code: string
                          rate: 0
                          seller_collectible:
                            amount: 0
                            currency: string
                          channel_collectible:
                            amount: 0
                            currency: string
                      custom_attributes:
                      - id: string
                        type: STRING
                    status_reason: ACCEPTANCE_TIMEOUT
                    fulfillment:
                      type: FULFILLED_BY_SELLER
                      code: string
                    billing_info:
                      address:
                        last_name: string
                        street: string
                        city: string
                        first_name: string
                        company: string
                        street_additional_info: string
                        state: string
                        country: string
                        country_iso_code: string
                        zip_code: string
                        phone: string
                        additional_info: string
                    has_incident: true
                    custom_attributes:
                    - id: string
                      type: STRING
                    sub_channel_code: string
            schema:
              $ref: '#/components/schemas/UpsertOrdersRequest'
        required: true
      responses:
        '204':
          description: No Content
        '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:orders:upsert
      summary: upsertOrders - Upsert orders
      tags:
      - Orders
    servers:
    - description: Connect Channel Platform API
      url: https://miraklconnect.com/api/channel-platform
  /orders/{order_id}/accept:
    put:
      deprecated: true
      description: '<div class="extension-title">Description</div>


        Use this API to accept or refuse order lines that are in the <code>AWAITING_ACCEPTANCE</code> status, from Mirakl Connect. The API also synchronizes the order line status on the sales channel. We recommend integrating this API in synchronous mode.


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

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


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

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

        </div>'
      operationId: acceptOrderLines
      parameters:
      - description: Order identifier in Mirakl Connect
        example: 0024_COMMERCIAL_ID-A
        explode: false
        in: path
        name: order_id
        required: true
        schema:
          type: string
        style: simple
      requestBody:
        content:
          application/json:
            examples:
              application/json-0:
                summary: Accept order request
                value:
                  order_lines:
                  - accepted: true
                    id: 0002_3202630-A-1
                  - accepted: false
                    id: 0002_3202630-A-2
              application/json-auto:
                summary: Complete example with value types (application/json)
                value:
                  order_lines:
                  - id: 0002_3202630-A-2
                    accepted: true
            schema:
              $ref: '#/components/schemas/AcceptOrderLinesRequest'
        required: true
      responses:
        '204':
          description: No content
        '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 order 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 order status has not been updated because the order does not exist.
      security:
      - Bearer:
        - connect:order:accept
      summary: acceptOrderLines - Accept or refuse order lines
      tags:
      - Orders
      x-badges:
      - color: noIntegrationBadge
        name: ⚠️ No Integration Allowed ⚠️
        position: after
    servers:
    - description: Connect Production endpoint
      url: https://miraklconnect.com/api
  /orders:
    get:
      deprecated: true
      description: '<div class="extension-title">Description</div>


        Use this API to synchronize Mirakl Connect orders with your system. We recommend integrating this API in asynchronous mode. You can retrieve all orders 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 order modification in Mirakl Connect (desc by default)</li><li><b>created_at</b> - Sort by date time the order was created on the sales channel (desc by default)</li></ul>


        </div>'
      operationId: listOrders
      parameters:
      - description: Filter by Connect order identifiers
        explode: true
        in: query
        name: order_ids
        required: false
        schema:
          type: array
          items:
            type: string
        style: form
      - description: Filter by order statuses
        explode: true
        in: query
        name: statuses
        required: false
        schema:
          type: array
          items:
            type: string
            enum:
            - AWAITING_FRAUD_CHECK
            - AWAITING_ACCEPTANCE
            - AWAITING_PAYMENT
            - AWAITING_SHIPMENT
            - SHIPPED
            - DELIVERED
            - CLOSED
        style: form
      - description: 'Select orders that were last updated in Mirakl Connect from the specified date time. If omitted and no `order_ids` filter is provided, defaults to 30 days ago.

          '
        explode: true
        in: query
        name: updated_from
        required: false
        schema:
          type: string
          format: date-time
          example: '2021-01-01T08:30:00Z'
        style: form
      - description: Filter by fulfillment channel
        explode: true
        in: query
        name: fulfillment_type
        required: false
        schema:
          type: string
          enum:
          - FULFILLED_BY_SELLER
          - FULFILLED_BY_PARTNER
        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 orders
        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 order
                  value:
                    data:
                    - billing_info:
                      

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