Products

Mirakl Platform (MMP)

Rest Seller APIs

OR74 - Upload documents to attach to an order

Mirakl Marketplace 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.

While most of our APIs support XML format, we strongly advise you to use JSON format, as our newest APIs are only available in JSON format.

Should you decide to validate our APIs output using XSD files, please note that your XSD should take into account the guidelines defined above. Mirakl does not provide XSD files for its APIs and does not offer support for writing XSD files.

Undocumented attributes

Some APIs may return more data than indicated in the documentation. Do not rely on this undocumented data, there is no guarantee about it.

Authentication

You can authenticate through API by sending your API key in a header.

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).

Shop Selection

When calling APIs as a shop, a request parameter shop_id is available. This parameter is useful when a user is associated to multiple shops and should be specified to select the shop to be used by the API.

Offset pagination & sort

Some APIs support offset pagination. In this case, you can use the max and offset parameters:

max: The max parameter is used to indicate the maximum number of items returned per page. This parameter is optional. The default value of this parameter is 10. The maximum value of this parameter is 100.
offset: The offset parameter is used to indicate the index of the first item (among all the results) in the returned page. This parameter is optional. The default value of this parameter is 0, which means that no offset is applied.

With pagination, the URL of the previous and/or next page can be returned in the header's attribute Link of the response.

When a sort parameter is available on such an API, it can be used to sort the results.

sort: The parameter sort is used to indicate how the results should be sorted. This parameter is optional. The possible values for this parameter are defined in resources. The default value of this parameter is defined in resources.

order: The parameter order is used to indicate the sort direction. This parameter is optional. The possible values for this parameter are asc (default) or desc.

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

Servers

URL to be replaced by your Mirakl instance URL

https://your-instance.mirakl.net/

Stores

Operations

Platform Settings

Operations

Invoicing and Accounting

Operations

Products

Operations

Messages

Operations

Offers

Operations

Orders

Operations

OR04 - Patch update orders

Request

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).

You cannot use API OR04 to update customer-related information if the customer has been anonymized via API AN01.

A maximum of 100 orders can be sent at once.

Call Frequency

Recommended usage: At each information update of one or multiple orders (for example: to modify the billing address)

Maximum usage: Once per minute, 100 orders per call

More context

Query

shop_idinteger(int64)

Use this parameter when your user has access to several shops. If not specified, the shop_id from your default shop will be used.

Bodyapplication/json

ordersArray of objects[ 1 .. 100 ] itemsrequired

Orders to be updated, maximum number of orders per call: 100

curl -i -X PUT \
  'https://your-instance.mirakl.net/api/orders?shop_id=0' \
  -H 'Content-Type: application/json' \
  -d '{
    "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"
          }
        ]
      }
    ]
  }'

Responses

Bodyapplication/json

updated_ordersArray of objects

A list of updated orders and orders in error objects

Response

application/json

{
  "updated_orders": [
    { … }
  ]
}

OR11 - List orders with pagination

Request

Pagination is enabled by default. For large requests, use asynchronous order export APIs OR13, OR14 and OR15 instead.

Call Frequency

Recommended usage:
- Asynchronous: every 5 minutes
- Synchronous: at each order page display

Maximum usage:
- Asynchronous: once per minute
- Synchronous: at each order page display

Pagination

This resource supports offset pagination (see documentation)

Sort fields

sort field can have the following values:

dateCreated (Default) - Sort by creation date, and then by order identifier (asc by default)

Localization

This resource supports locale parameter (see documentation)

Localized output fields will be highlighted with an icon:

Query

order_idsstring<= 100

A comma-separated list of order's identifiers

order_references_for_customerstring<= 100

A comma-separated list of order references for customer

order_references_for_sellerstring<= 100

A comma-separated list of order references for seller

order_state_codesstring

A comma-separated list of order state's codes

Enum"STAGING""WAITING_ACCEPTANCE""WAITING_DEBIT""WAITING_DEBIT_PAYMENT""SHIPPING""SHIPPED""TO_COLLECT""RECEIVED""CLOSED""REFUSED"

channel_codesstring<= 100

A comma-separated list of channel codes

only_null_channelboolean

Return only orders without channel. If true, ignore the channel_codes

Default false

start_datestring(date-time)

Start creation date for filtering

end_datestring(date-time)

End creation date for filtering

start_update_datestring(date-time)

Start update date for filtering. Mirakl will subtract a time delta to ensure no orders are missed due to network and/or software latency.

end_update_datestring(date-time)

End update date for filtering

customer_debitedboolean

Order paid by customer

payment_workflowstring

Payment workflow of an order

Enum"PAY_ON_ACCEPTANCE""PAY_ON_DELIVERY""PAY_ON_DUE_DATE""PAY_ON_SHIPMENT""NO_CUSTOMER_PAYMENT_CONFIRMATION"

has_incidentboolean

If true returns only orders with incidents in progress, if false returns orders without incidents in progress

Default "all"

fulfillment_center_codeArray of strings<= 100

Code of the fulfillment center

order_tax_modestring

Please note: If the taxes are not specified, the prices with mode TAX_EXCLUDED and with mode TAX_INCLUDED will return the same amounts.
Possible values:

TAX_EXCLUDED: the price fields (price, unit price, shipping price, cancellation amount, refund amount and order total prices) do not include taxes (taxes come on top of the price amount).
TAX_INCLUDED: the price fields include the tax amount.

If this query parameter is not specified, the default order tax mode of the platform is used.

Enum"TAX_INCLUDED""TAX_EXCLUDED"

shop_idinteger(int64)

Use this parameter when your user has access to several shops. If not specified, the shop_id from your default shop will be used.

curl -i -X GET \
  'https://your-instance.mirakl.net/api/orders?channel_codes=string&customer_debited=true&end_date=2019-08-24T14%3A15%3A22Z&end_update_date=2019-08-24T14%3A15%3A22Z&fulfillment_center_code=string&has_incident=all&only_null_channel=false&order_ids=string&order_references_for_customer=string&order_references_for_seller=string&order_state_codes=STAGING&order_tax_mode=TAX_INCLUDED&payment_workflow=PAY_ON_ACCEPTANCE&shop_id=0&start_date=2019-08-24T14%3A15%3A22Z&start_update_date=2019-08-24T14%3A15%3A22Z'

Responses

Bodyapplication/json

ordersArray of objectsrequired

List of orders

total_countinteger(int32)required

Total count of orders

Response

application/json

{
  "orders": [
    { … }
  ],
  "total_count": 1
}

OR07 - Update order line shipping origin

Request

Update shipping origin (shipping_from) information on order lines.

A maximum of 100 order lines can be sent at once.

Call Frequency

Recommended usage: At each update of shipping origin on one or multiple order lines

Maximum usage: 60 per hour, 100 order lines per call

Query

shop_idinteger(int64)

Use this parameter when your user has access to several shops. If not specified, the shop_id from your default shop will be used.

Bodyapplication/json

order_linesArray of objects[ 1 .. 100 ] itemsrequired

Order lines to be updated, maximum number of order lines per call: 100

curl -i -X PUT \
  'https://your-instance.mirakl.net/api/orders/shipping_from?shop_id=0' \
  -H 'Content-Type: application/json' \
  -d '{
    "order_lines": [
      {
        "id": "order-line-1",
        "shipping_from": {
          "warehouse": {
            "code": "DEFAULT_WAREHOUSE"
          }
        }
      }
    ]
  }'

Responses

Bodyapplication/json

order_linesArray of objects

A list containing each order line of the request, stating if the update was performed or failed.

Response

application/json

{
  "order_lines": [
    { … }
  ]
}

OR13 - Export orders asynchronously

Request

The API returns a tracking id to be used to query API OR14.
Mirakl recommends to use API OR13 instead of API OR11 as it can handle very large volumes of data.
You must give at least one date range filter: created or last updated date.
API OR13 supports the chunk of the export file into multiple files in order to:

respect a maximum megabyte weight using the megabytes_per_chunk parameter.
respect a maximum amount of exported items using the items_per_chunk parameter.

Only one export request can be created for the same shop account.

Call Frequency

Recommended usage:
- Differential: every 15 minutes

Maximum usage:
- Differential: every 5 minutes
- Full: every 24 hours

Localization

This resource supports locale parameter (see documentation)

Localized output fields will be highlighted with an icon:

Query

shop_idinteger(int64)

Use this parameter when your user has access to several shops. If not specified, the shop_id from your default shop will be used.

Bodyapplication/json

channel_codesArray of strings[ 0 .. 100 ] items

A list of channel codes

end_datestring(date-time)

End order creation date for filtering. Must be used with start_date.

end_update_datestring(date-time)

End order update date for filtering. Must be used with start_update_date.

fulfillment_center_codesstring[ 0 .. 100 ] characters

Code of the fulfillment center

items_per_chunkinteger(int64)[ 10000 .. 1000000 ]

Maximum number of items included in the generated files

Default 1000000

megabytes_per_chunkinteger(int64)[ 10 .. 1024 ]

Maximum mega bytes weight for generated files

Default 1024

only_null_channelboolean

Return only orders without channel. If true, ignore the channel_codes

Default false

order_state_codesArray of strings[ 0 .. 100 ] items

A list of order state's codes

Items Enum"STAGING""WAITING_ACCEPTANCE""WAITING_DEBIT""WAITING_DEBIT_PAYMENT""SHIPPING""SHIPPED""TO_COLLECT""RECEIVED""CLOSED""REFUSED"

order_tax_modestring

Please note: If the taxes are not specified, the prices with mode TAX_EXCLUDED and with mode TAX_INCLUDED will return the same amounts.
Possible values:

TAX_EXCLUDED: the price fields (price, unit price, shipping price, cancellation amount, refund amount and order total prices) do not include taxes (taxes come on top of the price amount).
TAX_INCLUDED: the price fields include the tax amount.

If this query parameter is not specified, the default order tax mode of the platform is used.

Enum"TAX_INCLUDED""TAX_EXCLUDED"

start_datestring(date-time)

Start order creation date for filtering. Must be used with end_date.

start_update_datestring(date-time)

Start order update date for filtering. Mirakl will subtract a time delta to ensure no orders are missed due to network and/or software latency. Must be used with end_update_date.

curl -i -X POST \
  'https://your-instance.mirakl.net/api/orders/async-export?shop_id=0' \
  -H 'Content-Type: application/json' \
  -d '{
    "channel_codes": [
      "US"
    ],
    "end_date": "2023-01-01T00:00:00.000Z",
    "end_update_date": "2020-08-19T14:58:22.460Z",
    "fulfillment_center_codes": "fulfillment_center_codes_001",
    "items_per_chunk": 10000,
    "megabytes_per_chunk": 100,
    "only_null_channel": false,
    "order_state_codes": [
      "WAITING_ACCEPTANCE",
      "SHIPPING"
    ],
    "order_tax_mode": "TAX_INCLUDED",
    "shop_ids": [
      2310
    ],
    "start_date": "2022-01-01T00:00:00.000Z",
    "start_update_date": "2019-08-20T14:58:22.460Z"
  }'

Responses

Asynchronous order export tracking creation success

Bodyapplication/json

tracking_idstringrequired

Id to poll in order to track the export's progress

Response

application/json

{
  "tracking_id": "tracking_id_001"
}

OR14 - Get the status of an asynchronous order export.

Request

Use this API to query the order export status after an API OR13 call.
Until the export via API OR13 is complete, the status returned by API OR14 is PENDING.
You must call API OR14 until you get the COMPLETED status which correspond to a completed and successful export from API OR13.
The URLs in API OR14 response contain all the files from API OR13 export.
Browse those urls and query them using the GET method.
In case of error, the status is FAILED.
In case of export canceled, the status is CANCELED.

Path

tracking_idstringrequired

Id of the previously created asynchronous order export

Query

shop_idinteger(int64)

Use this parameter when your user has access to several shops. If not specified, the shop_id from your default shop will be used.

curl -i -X GET \
  'https://your-instance.mirakl.net/api/orders/async-export/status/{tracking_id}?shop_id=0'

Responses

Order asynchronous export tracking polling success

Bodyapplication/json

last_updatedstring(date-time)required

The last updated date of the export

statusstringrequired

Current status of the export, can be 'PENDING', 'FAILED', or 'COMPLETED'

urlsArray of strings

List of generated URLs to call to download each generated chunks

Response

application/json

{
  "last_updated": "2022-08-18T15:20:22.906Z",
  "status": "COMPLETED",
  "urls": [
    "http://host:123/api/3f9edb57-9d8b-41e0-8b77-88d90caf7013?file=fileA",
    "http://host:123/api/3f9edb57-9d8b-41e0-8b77-88d90caf7013?file=fileB"
  ]
}

OR15 - Retrieve order export files once asynchronous export is complete (OR13).

Request

Retrieve each chunk of an order export file via the URL generated once the asynchronous export is complete.

Query

shop_idinteger(int64)

Use this parameter when your user has access to several shops. If not specified, the shop_id from your default shop will be used.

curl -i -X GET \
  'https://your-instance.mirakl.net/dynamic-url/The+URL+is+retrieved+from+OR14+output/OR15?shop_id=0'

Responses

Bodyapplication/json

ordersArray of objectsrequired

List of orders

Response

application/json

"string"

OR21 - Accept or refuse order lines

Request

Accept or refuse order lines in the WAITING_ACCEPTANCE status

Call Frequency

Recommended usage: At each new order on the Marketplace

Maximum usage: At each new order on the Marketplace

More context

Path

order_idstringrequired

Order's identifier

Query

shop_idinteger(int64)

Use this parameter when your user has access to several shops. If not specified, the shop_id from your default shop will be used.

Bodyapplication/json

order_linesArray of objectsrequired

List of representations of order line for acceptance

curl -i -X PUT \
  'https://your-instance.mirakl.net/api/orders/{order_id}/accept?shop_id=0' \
  -H 'Content-Type: application/json' \
  -d '{
    "order_lines": [
      {
        "accepted": true,
        "id": "Order_00012-B-1"
      }
    ]
  }'

Responses

No Content

OR23 - Update carrier tracking information for a specific order

Request

If the carrier is not registered, the complete tracking url can be provided.

Call Frequency

Recommended usage: At each order tracking information update (as soon as the seller gets the tracking number from the carrier)

Maximum usage: At each order tracking information update (as soon as the seller gets the tracking number from the carrier)

Path

order_idstringrequired

Order identifier

Query

shop_idinteger(int64)

Use this parameter when your user has access to several shops. If not specified, the shop_id from your default shop will be used.

Bodyapplication/json

carrier_codestring

The code of a carrier. This information is mandatory for a registered carrier.

carrier_namestring

The name of a carrier. This information is mandatory for an unregistered carrier.

carrier_standard_codestring

Carrier standard code

carrier_urlstring

The tracking url of a carrier. This information is unused for registered carriers (because computed automatically). This information is optional for unregistered carriers.

tracking_numberstring

The carrier tracking number. This information is mandatory for a registered carrier with a URL requiring a tracking number.

curl -i -X PUT \
  'https://your-instance.mirakl.net/api/orders/{order_id}/tracking?shop_id=0' \
  -H 'Content-Type: application/json' \
  -d '{
    "carrier_code": "UPS",
    "carrier_name": "UPS",
    "carrier_standard_code": "UPS",
    "carrier_url": "https://ups.com",
    "tracking_number": "5555"
  }'

Responses

No Content

OR24 - Validate the shipment of an order

Request

Validate the shipment of an order in the SHIPPING status

Call Frequency

Recommended usage: Each time the tracking number is entered (OR23)

Maximum usage: Each time the tracking number is entered (OR23)

Path

order_idstringrequired

Order's identifier

Query

shop_idinteger(int64)

Use this parameter when your user has access to several shops. If not specified, the shop_id from your default shop will be used.

curl -i -X PUT \
  'https://your-instance.mirakl.net/api/orders/{order_id}/ship?shop_id=0'

Responses

No Content

OR28 - Perform refunds on order lines

Request

Call Frequency

Recommended usage: At each refund request

Maximum usage: At each refund request

Query

shop_idinteger(int64)

Use this parameter when your user has access to several shops. If not specified, the shop_id from your default shop will be used.

Bodyapplication/json

order_tax_modestring

Please note: If the taxes are not specified, the prices with mode TAX_EXCLUDED and with mode TAX_INCLUDED will return the same amounts.
Possible values:

TAX_EXCLUDED: the price fields (price, unit price, shipping price and order total prices) do not include taxes (taxes come on top of the price amount).
TAX_INCLUDED: the price fields include the tax amounts.
If not specified, the default order tax mode of the platform is used.

Enum"TAX_INCLUDED""TAX_EXCLUDED"

refundsArray of objectsrequired

List of representations of refunds to be created

curl -i -X PUT \
  'https://your-instance.mirakl.net/api/orders/refund?shop_id=0' \
  -H 'Content-Type: application/json' \
  -d '{
    "order_tax_mode": "TAX_EXCLUDED",
    "refunds": [
      {
        "amount": 1.5,
        "currency_iso_code": "USD",
        "excluded_from_shipment": false,
        "fees": [
          {
            "amount": 0.5,
            "code": "CARD_FEE"
          },
          {
            "amount": 0.25,
            "code": "EU_DRS"
          }
        ],
        "order_line_id": "Order_00010-A-1",
        "quantity": 0,
        "reason_code": "15",
        "shipping_amount": 2,
        "shipping_taxes": [
          {
            "amount": "1",
            "code": "tax1"
          },
          {
            "amount": "1",
            "code": "tax2"
          }
        ],
        "tax_legal_notice": "Tax legal notice",
        "taxes": [
          {
            "amount": "1",
            "code": "tax1"
          },
          {
            "amount": "1",
            "code": "tax2"
          }
        ]
      }
    ]
  }'

Responses

Bodyapplication/json

order_tax_modestringrequired

Please note: In case there is no tax, the prices will show the same amount in TAX_EXCLUDED and TAX_INCLUDED mode. The tax mode is only useful if taxes are specified in the refund.
Possible values:

TAX_EXCLUDED: the price fields (amount, shipping amount) are expressed without tax (taxes should be added to these prices in order to get the full amount including taxes).
TAX_INCLUDED: the price fields include the tax amount.

Enum"TAX_INCLUDED""TAX_EXCLUDED"

refundsArray of objectsrequired

List of representations of created refunds

Response

application/json

{
  "order_tax_mode": "TAX_EXCLUDED",
  "refunds": [
    { … }
  ]
}

OR29 - Perform a full cancelation of an order

Request

Call Frequency

Recommended usage: At each order cancelation

Maximum usage: At each order cancelation

Path

order_idstringrequired

Order's identifier

Query

shop_idinteger(int64)

Use this parameter when your user has access to several shops. If not specified, the shop_id from your default shop will be used.

curl -i -X PUT \
  'https://your-instance.mirakl.net/api/orders/{order_id}/cancel?shop_id=0'

Responses

No Content

OR30 - Perform cancelations on order lines

Request

Call Frequency

Recommended usage: At each order (or order line) cancelation

Maximum usage: At each order (or order line) cancelation

Query

shop_idinteger(int64)

Use this parameter when your user has access to several shops. If not specified, the shop_id from your default shop will be used.

Bodyapplication/json

cancelationsArray of objectsrequired

List of representations of cancellations to be created

order_tax_modestring

Please note: If the taxes are not specified, the prices with mode TAX_EXCLUDED and with mode TAX_INCLUDED will return the same amounts.
Possible values:

TAX_EXCLUDED: the price fields (price, unit price, shipping price and order total prices) do not include taxes (taxes come on top of the price amount).
TAX_INCLUDED: the price fields include the tax amounts.
If not specified, the default order tax mode of the platform is used.

Enum"TAX_INCLUDED""TAX_EXCLUDED"

curl -i -X PUT \
  'https://your-instance.mirakl.net/api/orders/cancel?shop_id=0' \
  -H 'Content-Type: application/json' \
  -d '{
    "cancelations": [
      {
        "amount": 2,
        "currency_iso_code": "USD",
        "fees": [
          {
            "amount": 0.5,
            "code": "CARD_FEE"
          },
          {
            "amount": 0.25,
            "code": "EU_DRS"
          }
        ],
        "order_line_id": "Order_00013-A-1",
        "quantity": 0,
        "reason_code": 34,
        "shipping_amount": 0,
        "shipping_taxes": [
          {
            "amount": "1",
            "code": "tax1"
          },
          {
            "amount": "1",
            "code": "tax2"
          }
        ],
        "taxes": [
          {
            "amount": 1,
            "code": "tax1"
          },
          {
            "amount": 1,
            "code": "tax2"
          }
        ]
      }
    ],
    "order_tax_mode": "TAX_EXCLUDED"
  }'

Responses

Bodyapplication/json

cancelationsArray of objectsrequired

List of representations of created cancellations

order_tax_modestringrequired

Please note: In case there is no tax, the prices will show the same amount in TAX_EXCLUDED and TAX_INCLUDED mode. The tax mode is only useful if taxes are specified in the cancelation.
Possible values:

TAX_EXCLUDED: the price fields (amount, shipping amount) are expressed without tax (taxes should be added to these prices in order to get the full amount including taxes).
TAX_INCLUDED: the price fields include the tax amount.

Enum"TAX_INCLUDED""TAX_EXCLUDED"

Response

application/json

{
  "cancelations": [
    { … }
  ],
  "order_tax_mode": "TAX_EXCLUDED"
}

OR31 - Update the custom fields of an order and its order lines

Request

Only specified custom field values will be updated.
In order to delete an custom field's value, set it to null or an empty string. Note that you may not delete the value of a required custom field value.
Output will return information on the status of the update attempt by giving:

either all of the order and its order lines custom field values after the update
or in case of errors, the list of errors and the body of the initial call

Call Frequency

Recommended usage: Each time a custom field is updated on an order or on an order line

Maximum usage: Each time a custom field is updated on an order or on an order line

Path

order_idstringrequired

Order identifier

Query

shop_idinteger(int64)

Use this parameter when your user has access to several shops. If not specified, the shop_id from your default shop will be used.

Bodyapplication/json

order_additional_fieldsArray of objects

Order additional fields

order_linesArray of objects

Order lines additional fields

curl -i -X PUT \
  'https://your-instance.mirakl.net/api/orders/{order_id}/additional_fields?shop_id=0' \
  -H 'Content-Type: application/json' \
  -d '{
    "order_additional_fields": [
      {
        "code": "ecotax",
        "value": [
          "15"
        ]
      }
    ],
    "order_lines": [
      {
        "order_line_additional_fields": [
          {
            "code": "delivery-countries",
            "value": [
              "Canada"
            ]
          }
        ],
        "order_line_id": "Order_00014-A-1"
      }
    ]
  }'

Responses

Bodyapplication/json

order_update_errorsobject

Error report of an invalid request, with the body of the initial call

order_update_resultobject

Order and order line additional fields values after the update has been processed

Response

application/json

{
  "order_update_result": {
    "order_additional_fields": [ … ],
    "order_lines": [ … ]
  }
}

OR32 - Adjust order line

Request

Update order line actual measurement: it will create a refund or cancelation associated to the order line.

Call Frequency

Recommended usage: At each adjustment of one or multiple order lines

Maximum usage: Once per minute, 100 order lines per call

Query

shop_idinteger(int64)

Use this parameter when your user has access to several shops. If not specified, the shop_id from your default shop will be used.

Bodyapplication/json

order_linesArray of objects[ 1 .. 100 ] itemsrequired

Order lines to be updated, maximum number of order lines per call: 100

curl -i -X PUT \
  'https://your-instance.mirakl.net/api/orders/adjust?shop_id=0' \
  -H 'Content-Type: application/json' \
  -d '{
    "order_lines": [
      {
        "actual_measurement": 0.85,
        "order_line_id": "ORDER_0014-A-1"
      },
      {
        "actual_measurement": 1,
        "order_line_id": "ORDER_9999-A-1"
      }
    ]
  }'

Responses

Bodyapplication/json

order_lines_adjustedArray of objects

A list of updated order lines and orders in error objects

Response

application/json

{
  "order_lines_adjusted": [
    { … },
    { … }
  ]
}

OR51 - Get the evaluation of an order

Request

Call Frequency

Recommended usage: On each evaluation page view

Maximum usage: On each evaluation page view

Localization

This resource supports locale parameter (see documentation)

Localized output fields will be highlighted with an icon:

Path

order_idstringrequired

Query

shop_idinteger(int64)

Use this parameter when your user has access to several shops. If not specified, the shop_id from your default shop will be used.

curl -i -X GET \
  'https://your-instance.mirakl.net/api/orders/{order_id}/evaluation?shop_id=0'

Responses

Bodyapplication/json

assessmentsArray of objectsrequired

List of assessments

commentstring

Evaluation comment

customer_idstringrequired

Identifier of the customer who posted the evaluation

datestring(date-time)required

Evaluation creation date

firstnamestringrequired

First name of the customer who posted the evaluation

gradeinteger(int32)required

Evaluation grade

last_updated_datestring(date-time)required

Evaluation last updated date

lastnamestringrequired

Last name of the customer who posted the evaluation

replyobject

visiblebooleanrequired

Whether the evaluation is visible or not

Response

application/json

{
  "assessments": [
    { … },
    { … },
    { … },
    { … }
  ],
  "comment": "Great seller, I recommend!",
  "customer_id": "Customer-001",
  "date": "2019-04-03T09:46:17Z",
  "firstname": "Taylor",
  "grade": 4,
  "last_updated_date": "2019-04-03T09:46:17Z",
  "lastname": "Smith",
  "reply": {
    "comment": "Owww thks",
    "date": "2019-06-25T16:00:00Z",
    "type": "SHOP"
  },
  "visible": true
}

OR72 - Lists order's documents

Request

Returns a list of all the documents available on the order

Call Frequency

Recommended usage: At each document list page display

Maximum usage: At each document list page display

Query

order_idsstring<= 100required

the orders' identifiers, using comma as separator

shop_idinteger(int64)

Use this parameter when your user has access to several shops. If not specified, the shop_id from your default shop will be used.

curl -i -X GET \
  'https://your-instance.mirakl.net/api/orders/documents?order_ids=string&shop_id=0'

Responses

Bodyapplication/json

order_documentsArray of objectsrequired

The document details

total_countinteger(int32)Deprecated

Total number of documents

Response

application/json

{
  "order_documents": [
    { … },
    { … }
  ]
}

OR73 - Download one or multiple documents attached to one or multiple orders

Request

If a list of document identifiers is specified only these documents are downloaded.
- If more than one document id is specified, the documents will be wrapped in a ZIP archive
- If only one document id is specified the document will not be zipped
If a list of order identifiers is specified, all documents from those orders are downloaded.
Use a list of order document type codes to retrieve specific types from those orders.
In this case, the output of the API will always be a ZIP archive even if there is only one document to retrieve.

When documents are retrieved, they're wrapped into a ZIP archive except when only one document id is specified. The tree structure of this archive is as follow:


documents-timestamp.zip
|
|__ order_id_x/
|   |__ foo.txt
|   |__ bar.txt
|   |__ baz.pdf
|
|__ order_id_y/
|   |__ image.png
|   |__ image(1).png

Call Frequency

Recommended usage: At each document download

Maximum usage: At each document download

Query

order_idsstring<= 100

A list of identifiers of the orders (separated by a comma)

document_idsstring<= 100

A list of document identifiers (separated by a comma)

document_codesstring<= 100

A list of document type codes (separated by a comma)

shop_idinteger(int64)

Use this parameter when your user has access to several shops. If not specified, the shop_id from your default shop will be used.

curl -i -X GET \
  'https://your-instance.mirakl.net/api/orders/documents/download?document_codes=string&document_ids=string&order_ids=string&shop_id=0'

Responses

Bodyapplication/octet-stream

string(binary)

Response

application/octet-stream

string

OR74 - Upload documents to attach to an order

Request

Documents filenames must be distinct. Only documents of the following types are supported: csv, doc, xls, xlsx, ppt, pdf, odt, ods, odp, txt, rtf, png, jpg, gif, zpl, mov, mp4.
An order can have a maximum of 50 documents. In the API output we include only documents with errors. All other documents are successfully uploaded.

For system document types, there are specific restrictions :

SYSTEM_DELIVERY_BILL/SYSTEM_SHIPMENT_DELIVERY_BILL : restricted to operator role.
SYSTEM_MESSAGE_ATTACHMENT : cannot be directly uploaded to an order.

Call Frequency

Recommended usage: At each document upload on an order

Maximum usage: At each document upload on an order

Path

order_idstringrequired

The identifier of the order

Query

shop_idinteger(int64)

Use this parameter when your user has access to several shops. If not specified, the shop_id from your default shop will be used.

Bodymultipart/form-data

filesArray of strings(binary)required

The files to be uploaded. Use multipart/form-data with name 'files'. The file names must contain only US-ASCII characters.

order_documentsobjectrequired

The list of documents to be uploaded details

curl -i -X POST \
  'https://your-instance.mirakl.net/api/orders/{order_id}/documents?shop_id=0' \
  -H 'Content-Type: multipart/form-data' \
  -F 'files[0]=string' \
  -F 'order_documents[order_documents][0][entity][id]=string' \
  -F 'order_documents[order_documents][0][entity][type]=RETURN' \
  -F 'order_documents[order_documents][0][file_name]=string' \
  -F 'order_documents[order_documents][0][type_code]=string'

Responses

Bodyapplication/json

errors_countinteger(int32)

The number of documents in an error state

order_documentsArray of objectsrequired

Lists of error reports associated to each document in an error state

Response

application/json

{
  "errors_count": 1,
  "order_documents": [
    { … }
  ]
}

OR75 - List all the order taxes available on the platform

Request

Call Frequency

Recommended usage: Once per day

Maximum usage: Once per day

Localization

This resource supports locale parameter (see documentation)

Localized output fields will be highlighted with an icon:

Query

shop_idinteger(int64)

Use this parameter when your user has access to several shops. If not specified, the shop_id from your default shop will be used.

curl -i -X GET \
  'https://your-instance.mirakl.net/api/orders/taxes?shop_id=0'

Responses

Bodyapplication/json

taxesArray of objectsrequired

List of the order taxes

Response

application/json

{
  "taxes": [
    { … },
    { … },
    { … },
    { … }
  ]
}

OR76 - Delete an order document

Request

Call Frequency

Recommended usage: At each order document deletion

Maximum usage: At each order document deletion

Path

document_idinteger(int64)required

Identifier of the document to delete

Query

shop_idinteger(int64)

Use this parameter when your user has access to several shops. If not specified, the shop_id from your default shop will be used.

curl -i -X DELETE \
  'https://your-instance.mirakl.net/api/orders/documents/{document_id}?shop_id=0'

Responses

No Content

OR12 - Get information about an order⚠️ No Integration Allowed ⚠️Deprecated

Request

Call Frequency

Recommended usage: On each order page view

Maximum usage: On each order page view

Path

order_idstringrequired

Order's identifier

Query

shop_idinteger(int64)

Use this parameter when your user has access to several shops. If not specified, the shop_id from your default shop will be used.

curl -i -X GET \
  'https://your-instance.mirakl.net/api/orders/{order_id}?shop_id=0'

Responses

Bodyapplication/json

acceptance_decision_datestring(date-time)required

The date when the shop decided to accept or refuse the order

commercial_idstringrequired

Commercial's identifier of the order

created_datestring(date-time)required

Order's creation date

customerobject

Information of the customer who ordered

has_customer_messagebooleanrequired

Indicate if the customer has sent a message related to this order

has_incidentbooleanrequired

Indicate if order has an incident on at least one order line

has_invoicebooleanrequired

Is an invoice available for this order.

last_updated_datestring(date-time)required

Last update date of the order

order_idstringrequired

Order's identifier

order_linesArray of objectsrequired

Order lines

order_statestringrequired

Order's state

Enum"STAGING""WAITING_ACCEPTANCE""WAITING_DEBIT""WAITING_DEBIT_PAYMENT""SHIPPING""SHIPPED""TO_COLLECT""RECEIVED""CLOSED""REFUSED"

order_state_reason_codestringrequired

Reason code of the order state

order_state_reason_labelstringrequired

Reason label of the order state

payment_typestringrequired

Payment's type used by the customer to pay this order

pricenumber(with decimals)required

Order's price (sum of order line price)

shipping_companystring

Shipping company

shipping_pricenumber(with decimals)required

Order's shipping price (sum of order line shipping price)

shipping_trackingstring

Shipping tracking

shipping_tracking_urlstring

Shipping tracking url

shipping_type_codestringrequired

Code of shipping's type

shipping_type_labelstringrequired

Label of shipping's type

shipping_zone_codestringrequired

Code of shipping's zone

shipping_zone_labelstringrequired

Label of shipping's zone

total_commissionnumber(with decimals)required

Order's total commission (sum of the order line total commission)

total_pricenumber(with decimals)required

Order's total price (sum of the order price and the order shipping price)

paymenttypestringDeprecated

Payment's type used by the customer to pay this order

This field has been replaced by "payment_type" and will be removed soon.

Response

application/json

{
  "acceptance_decision_date": "2019-04-15T14:29:22Z",
  "commercial_id": "MIR-YCCYX80B",
  "created_date": "2019-04-15T14:29:09Z",
  "customer": {
    "billing_address": { … },
    "civility": "Ms.",
    "customer_id": "689-03-2780",
    "firstname": "Donna",
    "lastname": "Ford",
    "shipping_address": { … }
  },
  "has_customer_message": false,
  "has_incident": false,
  "has_invoice": false,
  "last_updated_date": "2019-04-15T14:29:23Z",
  "order_id": "MIR-YCCYX80B-A",
  "order_lines": [
    { … },
    { … }
  ],
  "order_state": "SHIPPING",
  "order_state_reason_code": null,
  "order_state_reason_label": null,
  "payment_type": "Credit Card",
  "price": 60,
  "shipping_company": null,
  "shipping_price": 5,
  "shipping_tracking": null,
  "shipping_tracking_url": null,
  "shipping_type_code": "CLC",
  "shipping_type_label": "Click & collect",
  "shipping_zone_code": "DOM1",
  "shipping_zone_label": "Domestic 1",
  "total_commission": 10.01,
  "total_price": 65
}

OR26 - Perform a refund of order lines of an order⚠️ No Integration Allowed ⚠️Deprecated

Request

Call Frequency

Recommended usage: On each new refund demand

Maximum usage: On each new refund demand

Path

order_idstringrequired

Order's identifier

Query

shop_idinteger(int64)

Use this parameter when your user has access to several shops. If not specified, the shop_id from your default shop will be used.

Bodyapplication/json

order_linesArray of objectsrequired

List of order line's representations

curl -i -X PUT \
  'https://your-instance.mirakl.net/api/orders/{order_id}/refund?shop_id=0' \
  -H 'Content-Type: application/json' \
  -d '{
    "order_lines": [
      {
        "id": "MIR-VOE5RDAE-A-1",
        "reason_code": 15
      }
    ]
  }'

Responses

No Content

OR41 - List messages of an order⚠️ No Integration Allowed ⚠️Deprecated

Request

By default, all sent, received and unarchived message are listed

Call Frequency

Recommended usage: On each message page view

Maximum usage: On each message page view

Pagination

This resource supports offset pagination (see documentation)

Sort fields

sort field can have the following values:

dateCreated (Default) - Sort by creation date (desc by default)

Path

order_idstringrequired

Order identifier

Query

receivedstring

If "TRUE" ("FALSE") returns only messages received by (sent to) shop.

Default "ALL"

Enum"TRUE""FALSE""ALL"

shop_idinteger(int64)

Use this parameter when your user has access to several shops. If not specified, the shop_id from your default shop will be used.

readstringDeprecated

Ignored, will be removed in a future version

Enum"TRUE""FALSE""ALL"

archivedstringDeprecated

Ignored, will be removed in a future version

Enum"TRUE""FALSE""ALL"

curl -i -X GET \
  'https://your-instance.mirakl.net/api/orders/{order_id}/messages?archived=TRUE&read=TRUE&received=TRUE&shop_id=0'

Responses

Bodyapplication/json

messagesArray of objectsrequired

List of messages

total_countinteger(int32)required

Total count of messages

Response

application/json

{
  "messages": [
    { … }
  ],
  "total_count": 1
}

OR81 - Upload the invoice of the order⚠️ No Integration Allowed ⚠️Deprecated

Request

Path

order_idstringrequired

Order identifier

Query

shop_idinteger(int64)

Use this parameter when your user has access to several shops. If not specified, the shop_id from your default shop will be used.

Bodymultipart/form-data

filestring(binary)required

Only documents of the following types are supported: csv, doc, xls, xlsx, ppt, pdf, odt, ods, odp, txt, rtf, png, jpg, gif, zpl. Use multipart/form-data with name file

curl -i -X POST \
  'https://your-instance.mirakl.net/api/orders/{order_id}/invoice?shop_id=0' \
  -H 'Content-Type: multipart/form-data' \
  -F file=string

Responses

Created

OR82 - Download the invoice of the order uploaded by the shop.⚠️ No Integration Allowed ⚠️Deprecated

Request

Path

order_idstringrequired

Order identifier

Query

shop_idinteger(int64)

Use this parameter when your user has access to several shops. If not specified, the shop_id from your default shop will be used.

curl -i -X GET \
  'https://your-instance.mirakl.net/api/orders/{order_id}/invoice?shop_id=0'

Responses

Bodyapplication/octet-stream

string(binary)

Response

application/octet-stream

string

Incidents

Operations

Picklists

Operations

Promotions

Operations

Returns

Operations

Multiple shipments

Operations

Mirakl Marketplace APIs

General Notes

Backward compatibility information

Undocumented attributes

Authentication

HTTPS only

API return codes

Success Codes

Error Codes

Rate limits

Request Content-Type

Response Content-Type

List of values as URL parameters

UTF-8 encoding

Locale

Date formats

Shop Selection

Offset pagination & sort

Seek pagination & sort

Stores

Platform Settings

Invoicing and Accounting

Products

Messages

Offers

Orders

OR04 - Patch update orders

RequestExpand all

Responses

OR11 - List orders with pagination

Request

Responses

OR07 - Update order line shipping origin

RequestExpand all

Responses

OR13 - Export orders asynchronously

Request

Responses

OR14 - Get the status of an asynchronous order export.

Request

Responses

OR15 - Retrieve order export files once asynchronous export is complete (OR13).

Request

Responses

OR21 - Accept or refuse order lines

RequestExpand all

Responses

OR23 - Update carrier tracking information for a specific order

Request

Responses

OR24 - Validate the shipment of an order

Request

Responses

OR28 - Perform refunds on order lines

RequestExpand all

Responses

OR29 - Perform a full cancelation of an order

Request

Responses

OR30 - Perform cancelations on order lines

RequestExpand all

Responses

OR31 - Update the custom fields of an order and its order lines

RequestExpand all

Responses

OR32 - Adjust order line

RequestExpand all

Responses

OR51 - Get the evaluation of an order

Request

Responses

OR72 - Lists order's documents

Request

Responses

OR73 - Download one or multiple documents attached to one or multiple orders

Request

Responses

OR74 - Upload documents to attach to an order

RequestExpand all

Responses

Request

Request

Request

Request

Request

Request

Request

Request

Request