Products
/
Connect
/
Connect APIs
/
Orders

Mirakl Connect APIs

General Notes

Backward compatibility information

Mirakl solutions are updated through continuous delivery to provide new features, security fixes and bug fixes.

New deployed versions are backward compatible, which guarantees the durability of your integration after a Mirakl solution update, on condition that your integration follows these guidelines:

  • Your integration must allow for new fields to be added in API responses. From time to time, we add new fields as part of new features.
  • Do not expect fields to always have the same order in API calls. The order can change when fields are added to APIs.
  • Your integration must allow for new values to be added in enumeration fields. We can add new values in enumeration fields to support new features. We advise that you use strings to deserialize enumeration fields. Alternatively, you can configure your deserializer to accept unknown enumeration values.

Authentication with OAuth 2.0

You must authenticate with Mirakl Authentication System to make API calls. Refer to the Mirakl documentation: About the Mirakl Authentication System.

HTTPS only

All requests must use the HTTPS protocol.

API return codes

Mirakl API uses standard HTTP return codes.

When making HTTP requests, you can check the success or failure status of your request by using the HTTP Status Codes (i.e. 200). You must not use the HTTP Status Messages or Reason-Phrases (i.e. OK), as they are optional and may not be returned in HTTP responses (see RFC9110 for more information).

Our API documentation does not document Reason-Phrases but provides a short contextualized description of HTTP Status Codes.

Success Codes

  • 200: OK - Request succeeded.
  • 201: Created - Request succeeded and resource created.
  • 202: Accepted - Request accepted for processing.
  • 204: No Content - Request succeeded but does not return any content.

Error Codes

  • 400: Bad Request - Parameter errors or bad method usage. Bad usage of the resource. For example: a required parameter is missing, some parameters use an incorrect format, a data query is not in the expected state.
  • 401: Unauthorized - API call without authentication. Add authentication information or use a valid authentication token.
  • 403: Forbidden - Access to the resource is denied. Current user can not access the resource.
  • 404: Not Found - The resource does not exist. The resource URI or the requested resource do not exist for the current user.
  • 405: Method Not Allowed - The HTTP method (GET, POST, PUT, DELETE) is not allowed for this resource. Refer to the documentation for the list of accepted methods.
  • 406: Not Acceptable - The requested response content type is not available for this resource. Refer to the documentation for the list of correct values of the Accept header for this request.
  • 410: Gone - The resource is permanently gone. The requested resource is no longer available and will not be available again.
  • 415: Unsupported Media Type - The entity content type sent to the server is not supported. Refer to the documentation for the list of correct values of the Content-type header to send data.
  • 429: Too many requests - Rate limits are exceeded. The user has sent too many requests in the last hour. Refer to the documentation for the maximum calls count per hour.
  • 500: Internal Server Error - The server encountered an unexpected error.

Rate limits

Mirakl APIs are protected by rate limits. Each API has a dedicated section displaying its rate limit.

If you make too many calls, you might receive an HTTP 429 "Too Many Requests" error. The response will contain a Retry-After header that specifies the number of seconds to wait before making a new request.

Request Content-Type

If an API request supports multiple Content-Types, add a Content-Type header to select the format to use in the request. The API documentation lists the formats an API can consume.

Response Content-Type

If an API response supports multiple Content-Types, add an Accept header to select the format accepted in the response. The API documentation lists the formats an API can produce.

List of values as URL parameters

array type fields indicate a list of values as URL parameters. You can add more parameter=value elements to the URL. Refer to the example in the right panel.

UTF-8 encoding

Text data is encoded in UTF-8.

Locale

If the API returns internationalized data, you can specify the locale parameter.

The Locale format is usually <ISO-639>_<ISO-3166> (e.g. "en_US"). There are some exceptions where the Locale format can be <ISO-639> (e.g. "en"). The locale returned in a response uses this format.

The APIs only accept locales that are equivalent to the languages activated in the back-office.

Date formats

APIs can use different date formats (compliant with ISO 8601):

  • date-time with the pattern YYYY-MM-DDThh:mm:ss[.SSS]±hh:mm.
    • The offset +00:00 can be replaced by Z (the zero UTC offset).
    • All APIs provide date-times in UTC, with the trailing Z.
    • Milliseconds may be omitted if equals to .000.
  • date-time-without-timezone with the pattern YYYY-MM-DDThh:mm:ss[.SSS].
    • The timezone does not appear.
    • Milliseconds may be omitted if equals to .000.
  • time with the pattern hh:mm[:ss][.SSS]±hh:mm. Time only, with timezone
    • The offset +00:00 can be replaced by Z (the zero UTC offset).
    • Seconds may be omitted if equals to :00.
    • Milliseconds may be omitted if equals to .000.

In the patterns:

  • YYYY: years (four-digit)
  • MM: months, 01-12 (two-digit)
  • DD: days, 01-31 (two-digit)
  • T is a delimiter between the date and time
  • hh: hours, 00-23 (two-digit)
  • mm: minutes, 00-59 (two-digit)
  • ss: seconds, 00-60 (two-digit)
  • SSS: milliseconds, 000-999 (three-digit)
  • ±hh:mm: refers to an offset from UTC

For GET requests, use URL encoding (for example, 2019-08-29T02:34:00+02:00 becomes 2019-08-29T02%3A34%3A00%2B02%3A00).

Seek pagination & sort

For better performance and user experience, some APIs support "seek" pagination. This means that you cannot go directly to the N-th page.

Use the optional limit query parameter to indicate the maximum number of items returned per page. The default value is 10. The maximum value is 100.

If there are more results to return, the response contains a next_page_token field. Pass this value in the page_token query parameter to return the next page of results.

The API also returns a previous_page_token when the result is not the first page. Use it the same way as next_page_token.

Values of next_page_token and previous_page_token contain all required parameters to access next and previous page. When using the page_token parameter all other parameters are ignored, regardless of the value given to page_token.

When a sort parameter is available, it must follow the sort=criterion,direction format where:

  • criterion is the name of the criterion to sort by (e.g: date_created, title, ...)
  • direction is the sort direction. Can be one of ASC, DESC
Languages
Servers
Connect Production endpoint
https://miraklconnect.com/api/

Fulfillment by logistics partner

Operations

Orders

Operations

v2-acceptOrderLines - Accept or refuse order lines

Request

Use this API to accept or refuse order lines that are in the AWAITING_ACCEPTANCE status, from Mirakl Connect. The API also synchronizes the order line status on the sales channel.

Call Frequency
Recommended usage: On each new order
Maximum usage: On each new order

Path
order_idstringrequired

Order identifier in Mirakl Connect

Example: 0024_COMMERCIAL_ID-A
Bodyapplication/jsonrequired
order_linesArray of objectsnon-emptyrequired

Information about ordered products

curl -i -X PUT \
  https://miraklconnect.com/api/v2/orders/0024_COMMERCIAL_ID-A/accept \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "order_lines": [
      {
        "accepted": true,
        "id": "0002_3202630-A-1"
      },
      {
        "accepted": false,
        "id": "0002_3202630-A-2"
      }
    ]
  }'

Responses

Accepted. The accept request will be processed asynchronously.

Bodyapplication/json
action_idstringrequired

The unique identifier for the asynchronous action. It should be used with the v2-getStatus API to retrieve current action status and potential errors.

Example: "1ba5fc4b-c4fd-4251-880b-3052e301bbd4"
tracking_idstringDeprecated

Deprecated: This field was previously used to obtain the action ID. It has been replaced by action_id and contains the same value. It is retained for backward compatibility.

Example: "1ba5fc4b-c4fd-4251-880b-3052e301bbd4"
Response
application/json
{
  "action_id": "1ba5fc4b-c4fd-4251-880b-3052e301bbd4",
  "tracking_id": "1ba5fc4b-c4fd-4251-880b-3052e301bbd4"
}

v2-cancelOrderLines - Cancel order lines

Request

Use this API to cancel order lines (all or part) of an order.

Call Frequency
Recommended usage: At each cancel request
Maximum usage: At each cancel request

Path
order_idstringrequired

Order identifier in Mirakl Connect

Example: 0024_COMMERCIAL_ID-A
Bodyapplication/jsonrequired
cancelationsArray of objectsnon-emptyrequired

Cancelations details related to an order

curl -i -X POST \
  https://miraklconnect.com/api/v2/orders/0024_COMMERCIAL_ID-A/cancel \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "cancelations": [
      {
        "order_line_id": "0002_3202630-A-1",
        "price": {
          "amount": 15,
          "currency": "USD"
        },
        "product_id": "10000",
        "quantity": 1,
        "reason": "CUSTOMER_CANCELATION",
        "shipping_price": {
          "amount": 8,
          "currency": "USD"
        },
        "shipping_taxes": [
          {
            "amount": {
              "amount": 3,
              "currency": "USD"
            },
            "code": "ShippingTax1"
          },
          {
            "amount": {
              "amount": 4,
              "currency": "USD"
            },
            "code": "ShippingTax2"
          }
        ],
        "taxes": [
          {
            "amount": {
              "amount": 1,
              "currency": "USD"
            },
            "code": "Tax1"
          },
          {
            "amount": {
              "amount": 2,
              "currency": "USD"
            },
            "code": "Tax2"
          }
        ]
      }
    ]
  }'

Responses

Accepted. The cancel request will be processed asynchronously.

Bodyapplication/json
action_idstringrequired

The unique identifier for the asynchronous action. It should be used with the v2-getStatus API to retrieve current action status and potential errors.

Example: "1ba5fc4b-c4fd-4251-880b-3052e301bbd4"
tracking_idstringDeprecated

Deprecated: This field was previously used to obtain the action ID. It has been replaced by action_id and contains the same value. It is retained for backward compatibility.

Example: "1ba5fc4b-c4fd-4251-880b-3052e301bbd4"
Response
application/json
{
  "action_id": "1ba5fc4b-c4fd-4251-880b-3052e301bbd4",
  "tracking_id": "1ba5fc4b-c4fd-4251-880b-3052e301bbd4"
}

v2-getActionStatus - Track an asynchronous action request

Request

Use this API to check the status of an asynchronous action request (e.g., v2-acceptOrderLines) and retrieve any potential errors that occurred during the action processing. We recommend integrating this API asynchronously.

Call Frequency
Recommended usage: Asynchronous: every 5 minutes per action ID
Maximum usage: Asynchronous: once per minute per action ID

Path
action_idstringrequired

The unique identifier that is returned when an asynchronous action (e.g., v2-acceptOrderLines) is requested.

Example: 1ba5fc4b-c4fd-4251-880b-3052e301bbd4
curl -i -X GET \
  https://miraklconnect.com/api/v2/orders/actions/1ba5fc4b-c4fd-4251-880b-3052e301bbd4 \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Details of the action, including current status and potential errors

Bodyapplication/json
created_atstring(date-time)required

Action creation date

Example: "2021-07-06T09:24:36.32Z"
errorsArray of objects

List of errors that occurred during the action processing

idstringrequired

The unique identifier for the asynchronous action. This ID is generated when the action is initially requested.

Example: "1ba5fc4b-c4fd-4251-880b-3052e301bbd4"
status"PENDING" (string) or "SUCCESS" (string) or "FAILED" (string)required

Current action status

Example: "PENDING"
One of:

Current action status

string("PENDING")

Current action status

updated_atstring(date-time)required

Date of last modification of the action status

Example: "2021-07-06T09:24:36.32Z"
Response
application/json
{
  "created_at": "2021-11-30T18:35:24Z",
  "id": "1ba5fc4b-c4fd-4251-880b-3052e301bbd4",
  "status": "SUCCESS",
  "updated_at": "2021-11-30T18:38:24Z"
}

v2-listOrders - List Mirakl Connect orders

Request

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 updated_from parameter valued with the last execution time of the task.

Call Frequency
Recommended usage: Asynchronous: every 5 minutes
Maximum usage: Asynchronous: once per minute
Pagination

This resource supports seek pagination (see documentation)

Sort fields
sort field can have the following values:
  • updated_at (Default) - Sort by date time of last order modification in Mirakl Connect (desc by default)
  • created_at - Sort by date time the order was created on the sales channel (desc by default)

Query
order_idsArray of strings

Filter by Connect order identifiers

statusesArray of strings

Filter by order statuses

Items Enum"AWAITING_FRAUD_CHECK""AWAITING_ACCEPTANCE""AWAITING_PAYMENT""AWAITING_SHIPMENT""SHIPPED""DELIVERED""CLOSED"
updated_fromstring(date-time)

Select orders that were last updated in Mirakl Connect from the specified date time.

Example: updated_from=2021-01-01T08:30:00Z
fulfillment_typestring

Filter by fulfillment channel

Enum"FULFILLED_BY_SELLER""FULFILLED_BY_PARTNER"
page_tokenstring

Token to access the next or previous page

limitinteger[ 1 .. 100 ]

Maximum number of listed orders

Default 10
curl -i -X GET \
  'https://miraklconnect.com/api/v2/orders?fulfillment_type=FULFILLED_BY_SELLER&limit=10&order_ids=string&page_token=string&statuses=AWAITING_FRAUD_CHECK&updated_from=2021-01-01T08%3A30%3A00Z' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

List of orders

Bodyapplication/json
next_page_tokenstringnon-empty

Token to access the next page. Absent if the current page is the last one.

previous_page_tokenstringnon-empty

Token to access the previous page. Absent if the current page is the first one.

dataArray of objectsrequired

Page of orders corresponding to the filter parameters

Response
application/json
{
  "data": [
    { … },
    { … }
  ],
  "next_page_token": "bGltaXQ9MTAmYWZ0ZXI9MjAyMS0xMS0xNlQxNjoxNTowOSswMTowMCZhZnRlcj1jb25uZWN0bXAxLXRlc3QmYWZ0ZXI9MzE3ODczOC1BJnNvcnQ9ZGF0ZV91cGRhdGVkLERFU0M=",
  "previous_page_token": "YmVmb3JlPTIwMjEtMTEtMjRUMDA6MDA6MTErMDE6MDAmYmVmb3JlPWNvbm5lY3RtcDItdGVzdCZiZWZvcmU9MzIwMjYzMC1BJmxpbWl0PTEwJnNvcnQ9ZGF0ZV91cGRhdGVkLERFU0M="
}

v2-refundOrderLines - Refund order lines

Request

Use this API to refund order lines (all or part) of an order.

Call Frequency
Recommended usage: At each refund request
Maximum usage: At each refund request

Path
order_idstringrequired

Order identifier in Mirakl Connect

Example: 0024_COMMERCIAL_ID-A
Bodyapplication/jsonrequired
refundsArray of objectsnon-emptyrequired

Refund details related to an order line

curl -i -X POST \
  https://miraklconnect.com/api/v2/orders/0024_COMMERCIAL_ID-A/refund \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "refunds": [
      {
        "order_line_id": "0002_3202630-A-1",
        "price": {
          "amount": 15,
          "currency": "USD"
        },
        "product_id": "10000",
        "quantity": 1,
        "reason": "ITEM_NOT_RECEIVED",
        "shipping_price": {
          "amount": 8,
          "currency": "USD"
        },
        "shipping_taxes": [
          {
            "amount": {
              "amount": 3,
              "currency": "USD"
            },
            "code": "ShippingTax1"
          },
          {
            "amount": {
              "amount": 4,
              "currency": "USD"
            },
            "code": "ShippingTax2"
          }
        ],
        "taxes": [
          {
            "amount": {
              "amount": 1,
              "currency": "USD"
            },
            "code": "Tax1"
          },
          {
            "amount": {
              "amount": 2,
              "currency": "USD"
            },
            "code": "Tax2"
          }
        ]
      }
    ]
  }'

Responses

Accepted. The refund request will be processed asynchronously.

Bodyapplication/json
action_idstringrequired

The unique identifier for the asynchronous action. It should be used with the v2-getStatus API to retrieve current action status and potential errors.

Example: "1ba5fc4b-c4fd-4251-880b-3052e301bbd4"
tracking_idstringDeprecated

Deprecated: This field was previously used to obtain the action ID. It has been replaced by action_id and contains the same value. It is retained for backward compatibility.

Example: "1ba5fc4b-c4fd-4251-880b-3052e301bbd4"
Response
application/json
{
  "action_id": "1ba5fc4b-c4fd-4251-880b-3052e301bbd4",
  "tracking_id": "1ba5fc4b-c4fd-4251-880b-3052e301bbd4"
}

acceptOrderLines - Accept or refuse order lines⚠️ No Integration Allowed ⚠️Deprecated

Request

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

Call Frequency
Recommended usage: On each new order
Maximum usage: On each new order

Path
order_idstringrequired

Order identifier in Mirakl Connect

Example: 0024_COMMERCIAL_ID-A
Bodyapplication/jsonrequired
order_linesArray of objectsnon-emptyrequired

Information about ordered products

curl -i -X PUT \
  https://miraklconnect.com/api/orders/0024_COMMERCIAL_ID-A/accept \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "order_lines": [
      {
        "accepted": true,
        "id": "0002_3202630-A-1"
      },
      {
        "accepted": false,
        "id": "0002_3202630-A-2"
      }
    ]
  }'

Responses

No content

Response
No content

listOrders - List Mirakl Connect orders⚠️ No Integration Allowed ⚠️Deprecated

Request

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 updated_from parameter valued with the last execution time of the task.

Call Frequency
Recommended usage: Asynchronous: every 5 minutes
Maximum usage: Asynchronous: once per minute
Pagination

This resource supports seek pagination (see documentation)

Sort fields
sort field can have the following values:
  • updated_at (Default) - Sort by date time of last order modification in Mirakl Connect (desc by default)
  • created_at - Sort by date time the order was created on the sales channel (desc by default)

Query
order_idsArray of strings

Filter by Connect order identifiers

statusesArray of strings

Filter by order statuses

Items Enum"AWAITING_FRAUD_CHECK""AWAITING_ACCEPTANCE""AWAITING_PAYMENT""AWAITING_SHIPMENT""SHIPPED""DELIVERED""CLOSED"
updated_fromstring(date-time)

Select orders that were last updated in Mirakl Connect from the specified date time.

Example: updated_from=2021-01-01T08:30:00Z
fulfillment_typestring

Filter by fulfillment channel

Enum"FULFILLED_BY_SELLER""FULFILLED_BY_PARTNER"
page_tokenstring

Token to access the next or previous page

limitinteger[ 1 .. 100 ]

Maximum number of listed orders

Default 10
curl -i -X GET \
  'https://miraklconnect.com/api/orders?fulfillment_type=FULFILLED_BY_SELLER&limit=10&order_ids=string&page_token=string&statuses=AWAITING_FRAUD_CHECK&updated_from=2021-01-01T08%3A30%3A00Z' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

List of orders

Bodyapplication/json
next_page_tokenstringnon-empty

Token to access the next page. Absent if the current page is the last one.

previous_page_tokenstringnon-empty

Token to access the previous page. Absent if the current page is the first one.

dataArray of objectsrequired

Page of orders corresponding to the filter parameters

Response
application/json
{
  "data": [
    { … },
    { … }
  ],
  "next_page_token": "bGltaXQ9MTAmYWZ0ZXI9MjAyMS0xMS0xNlQxNjoxNTowOSswMTowMCZhZnRlcj1jb25uZWN0bXAxLXRlc3QmYWZ0ZXI9MzE3ODczOC1BJnNvcnQ9ZGF0ZV91cGRhdGVkLERFU0M=",
  "previous_page_token": "YmVmb3JlPTIwMjEtMTEtMjRUMDA6MDA6MTErMDE6MDAmYmVmb3JlPWNvbm5lY3RtcDItdGVzdCZiZWZvcmU9MzIwMjYzMC1BJmxpbWl0PTEwJnNvcnQ9ZGF0ZV91cGRhdGVkLERFU0M="
}

v2-getOrderTracking - Retrieve tracking information⚠️ No Integration Allowed ⚠️Deprecated

Request

This API is deprecated. Please use the new v2-getActionStatus API for retrieving the status of action request and potential errors.

Call Frequency
Recommended usage: Uses the new v2-getActionStatus API
Maximum usage: Uses the new v2-getActionStatus API

Path
tracking_idstringDeprecatedrequired

Order Tracking identifier in Mirakl Connect

Example: 1ba5fc4b-c4fd-4251-880b-3052e301bbd4
curl -i -X GET \
  https://miraklconnect.com/api/v2/orders/tracking/1ba5fc4b-c4fd-4251-880b-3052e301bbd4 \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Order tracking information

Bodyapplication/json
created_atstring(date-time)required

Tracking creation date

Example: "2021-07-06T09:24:36.32Z"
errorsArray of objects

List of errors that occurred during the tracking process

idstringrequired

Tracking identifier in Mirakl Connect

Example: "1ba5fc4b-c4fd-4251-880b-3052e301bbd4"
status"PENDING" (string) or "SUCCESS" (string) or "FAILED" (string)required

Current tracking status

Example: "PENDING"
One of:

Current tracking status

string("PENDING")

Current tracking status

updated_atstring(date-time)required

Date of last modification of the order tracking

Example: "2021-07-06T09:24:36.32Z"
Response
application/json
{
  "created_at": "2021-11-30T18:35:24Z",
  "id": "1ba5fc4b-c4fd-4251-880b-3052e301bbd4",
  "status": "SUCCESS",
  "updated_at": "2021-11-30T18:38:24Z"
}

Shipments

Operations

Catalog

Operations