Mirakl Orders API

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 Orders API
  version: ''
servers:
- description: Connect Channel Platform API
  url: https://miraklconnect.com/api/channel-platform
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
  /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
  /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
  /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"
  /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
  /api/orders:
    put:
      description: '<div class="extension-title">Description</div>


        <p>Update orders information field by field: unspecified fields will not be updated. To remove the value for a field, send it with the ''null'' value (not allowed for the required fields).</p><p>You cannot use API OR04 to update customer-related information if the customer has been anonymized via API AN01.</p><p><span class=''red''>A maximum of 100 orders can be sent at once.</span></p>


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

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


        <div class="recommended-call-frequency">Recommended usage: At each information update of one or multiple orders (for example: to modify the billing address)</div>

        <div class="max-call-frequency">Maximum usage: Once per minute, 100 orders per call</div>

        <div class="extension-title">Read More</div>


        <ul><li><a href="https://help.mirakl.com/bundle/customers/page/topics/Mirakl/integrating_mirakl/update_orders_info.htm">More context</a></li><li><a href="https://help.mirakl.com/bundle/customers/page/topics/Mirakl/integrating_mirakl/create_orders/organization_data.htm">If the customer organization feature is activated, read this page</a></li></ul></div>'
      operationId: OR04
      parameters: []
      requestBody:
        content:
          application/json:
            examples:
              application/json-0:
                summary: Updating several order information
                value:
                  orders:
                  - customer:
                      accounting_contact:
                        customer_id: Customer_id_002
                      billing_address:
                        city: New York
                        company: simple customer
                        company_2: second information
                        country: USA
                        country_iso_code: USA
                        phone_secondary: 213-509-6995
                        state: Manhattan
                        street_1: 113 MacDougal Street
                        street_2: 1st floor
                        zip_code: NY 10012
                      delivery_contact:
                        customer_id: Customer_id_003
                      organization:
                        address:
                          city: New York
                          country_iso_code: USA
                          state: Manhattan
                          street_1: 113 MacDougal Street
                          street_2: 1st floor
                          zip_code: NY 10012
                        identification_number: '982837446'
                        name: Limark Company Inc.
                        tax_identification_number: 96-25472919
                      shipping_address:
                        additional_info: One article per box
                        city: New York
                        civility: M
                        company: LIMARK Company
                        company_2: Paris branch
                        country: USA
                        country_iso_code: USA
                        firstname: Smith
                        internal_additional_info: No additional information
                        lastname: Taylor
                        phone: 213-509-6995
                        phone_secondary: 213-509-6996
                        state: Manhattan
                        street_1: 113 MacDougal Street
                        street_2: 1st floor
                        zip_code: NY 10012
                    invoice_details:
                      document_details:
                      - format: PDF
                      - format: cXML
                      payment_terms:
                        days: 10
                        type: NET
                    order_id: Order_00014
                    payment_destination:
                      '@type': IBAN
                      iban: '123456789'
                      payment_reference: TX1000
                    payment_workflow: PAY_ON_ACCEPTANCE
                    shipping_deadline: '2020-03-20T16:38:31.131Z'
                    shop_statistics:
                      excluded: true
                      reason: Reason for exclusion
              application/json-1:
                summary: Updating the billing address
                value:
                  orders:
                  - customer:
                      billing_address:
                        city: New York
                        company: simple customer
                        company_2: second information
                        country: USA
                        country_iso_code: USA
                        phone_secondary: 213-509-6995
                        state: Manhattan
                        street_1: 113 MacDougal Street
                        street_2: 1st floor
                        zip_code: NY 10012
                    order_id: Order_00014
              application/json-2:
                summary: Updating shipping deadlines
                value:
                  orders:
                  - order_id: Order_00014
                    shipping_deadline: '2020-03-20T16:38:31.131Z'
              application/json-3:
                summary: Updating payment workflow
                value:
                  orders:
                  - order_id: Order_00014
                    payment_workflow: PAY_ON_ACCEPTANCE
              application/json-4:
                summary: Excluding order from store statistics
                value:
                  orders:
                  - order_id: Order_00014
                    shop_statistics:
                      excluded: true
                      reason: Reason for exclusion
              application/json-5:
                summary: Updating order references
                value:
                  orders:
                  - order_id: Order_00014
                    references:
                      order_reference_for_customer: ref_customer
                      order_reference_for_seller: ref_seller
              application/json-6:
                summary: Updating customer organization data
                value:
                  orders:
                  - customer:
                      accounting_contact:
                        customer_id: Customer_id_002
                      delivery_contact:
                        customer_id: Customer_id_003
                      organization:
                        address:
                          city: New York
                          country_iso_code: USA
                          state: Manhattan
                          street_1: 113 MacDougal Street
                          street_2: 1st floor
                          zip_code: NY 10012
                        identification_number: '982837446'
                        name: Limark Company Inc.
                        tax_identification_number: 96-25472919
                    order_id: Order_00014
              application/json-7:
                summary: Updating eco-contributions
                value:
                  orders:
                  - order_id: Order_00014
                    order_lines:
                    - eco_contributions:
                      - epr_category_code: FR-DEEE
                        producer_id: '123456789012345'
                        unit_amount: 1.25
                      - epr_category_code: FR-ASL
                        producer_id: FRASLPRODUCERID
                        unit_amount: 1.1
                      order_line_id: Order_00014-A-1
              application/json-auto:
                summary: Complete example with value types (application/json)
                value:
                  orders:
                  - customer:
                      accounting_contact:
                        customer_id: string
                      billing_address:
                        city: string
                        civility: string
                        company: string
                        company_2: string
                        country: string
                        country_iso_code: AFG
                        firstname: string
                        lastname: string
                        phone: string
                        phone_secondary: string
                        state: string
                        street_1: string
                        street_2: string
                        zip_code: 

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