Products
/
Mirakl Platform
/
Rest Seller APIs
/
Messages

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
Languages
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

M10 - Retrieve a thread

Request

Call Frequency
Recommended usage: Synchronous only - At each page that includes a message thread display
Maximum usage: Synchronous only - At each page that includes a message thread display
Path
thread_idstringrequired

The identifier of the thread to retrieve.

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/inbox/threads/{thread_id}?shop_id=0'

Responses

OK

Bodyapplication/json
authorized_participantsArray of objectsrequired

Thread authorized participants
Those are the participants who are authorized to join the thread.

current_participantsArray of objectsrequired

Thread current participants
Those are the participants who have actually participated in the thread, meaning that they are either sender or receivers of at least one message of the thread.
These participants must be on the list of the authorized_participants

customer_organizationobject

Data related to the customer organization (B2B transactions)

date_createdstring(date-time)required

Thread created date

date_updatedstring(date-time)required

Thread updated date

entitiesArray of objects

Thread entities

idstringrequired

Thread id

messagesArray of objectsrequired

Thread messages

metadataobjectrequired

Thread metadata

no_store_reply_neededArray of objects

Thread "no store reply needed" actions.

topicobjectrequired

Thread topic

Response
application/json
{
  "authorized_participants": [
    { … },
    { … }
  ],
  "current_participants": [
    { … },
    { … }
  ],
  "customer_organization": {
    "display_name": "Customer organization",
    "id": "customer-org-id"
  },
  "date_created": "2018-10-02T08:36:36.479Z",
  "date_updated": "2018-10-03T09:40:17.241Z",
  "entities": [
    { … }
  ],
  "id": "702c3e56-dcca-41e2-b6bd-72ba3fa809be",
  "messages": [
    { … },
    { … }
  ],
  "metadata": {
    "last_message_date": "2018-10-03T09:40:17.241Z",
    "last_sender": { … },
    "shop_reply_needed_since": null,
    "total_count": 2
  },
  "no_store_reply_needed": [],
  "topic": {
    "type": "FREE_TEXT",
    "value": "Questions about my order"
  }
}

M11 - List all threads

Request

You may want to retrieve the threads linked to a specific entity, using both entity_type and entity_id.
For example, to retrieve threads for an order, use entity_type=MMP_ORDER&entity_id=my-order-1.
Available values for entity_type are:

  • MMP_ORDER: for threads on product orders
  • MMP_OFFER: for threads on offers
  • MPS_ORDER: for threads on service orders
  • MPS_SERVICE: for threads on services
  • SELLER_OPERATOR: for threads between sellers and operator

This resource uses seek pagination. The default value for parameter limit is 50.

Call Frequency
Recommended usage: Synchronous only - At each page that includes an inbox display
Maximum usage: Synchronous only - At each page that includes an inbox display
Pagination

This resource supports seek pagination (see documentation)

Query
entity_typestring

Entity type to include in result (default: include all).
Available values: MMP_ORDER, MMP_OFFER, MPS_ORDER, MPS_SERVICE, SELLER_OPERATOR

entity_idArray of strings

Comma separated list of Entity id to include in result (default: include all).
The entity_type must be specified to use this filter, otherwise an error 400 will be returned.
Example of an entity_id query: entity_id=order1-A,order20-A,order13-A&entity_type=MMP_ORDER

updated_sincestring(date-time)

Retrieve threads modified at or after this date.

with_messagesboolean

True to include message details. Limited to the last 100 messages received on each thread.

Default false
channel_codesArray of stringsunique

List of the channel codes to filter with, using a comma (,) as a separator.
If specified, only order messages linked to the given channels will be returned (Whatever the value of entity_type).
Otherwise, messages will be returned regardless of their channels.

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/inbox/threads?channel_codes=string&entity_id=string&entity_type=string&shop_id=0&updated_since=2019-08-24T14%3A15%3A22Z&with_messages=false'

Responses

OK

Bodyapplication/json
dataArray of objectsrequired

Page of data

next_page_tokenstring

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

previous_page_tokenstring

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

Response
application/json
{
  "data": [
    { … }
  ],
  "next_page_token": "bGltaXQ9NTAmYWZ0ZXI9MjA3NjYwNTAtZDc5Yy00YzUyLWEwODctZWI5YjY1MjFkNzA5JnNvcnQ9ZGF0ZSxERVND.jFoPX_GjfbaRV88hhNxWWEzeRSqPt1WNExsrcBTkuSY="
}

M14 - Create a thread with the operator

Request

Create a thread with the operator and send a first message

Call Frequency
Recommended usage: Synchronous only - At each thread
Maximum usage: Synchronous only - At each thread answer

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)

List of attachments for the message
Maximum 1000 across all threads of the same entity.
For example, for a given seller, you can not have more than 1000 attachments across all its threads.

thread_inputobjectrequired

Message and thread data

curl -i -X POST \
  'https://your-instance.mirakl.net/api/inbox/threads?shop_id=0' \
  -H 'Content-Type: multipart/form-data' \
  -F files=string \
  -F 'thread_input[body]=string' \
  -F 'thread_input[entity][type]=string' \
  -F 'thread_input[topic][type]=FREE_TEXT' \
  -F 'thread_input[topic][value]=string'

Responses

Created

Bodyapplication/json
message_idstring

Id of the message

thread_idstring

Id of the thread

Response
application/json
{
  "message_id": "873f1cb5-a7a2-4e07-8e0e-12eb64e93ece",
  "thread_id": "702c3e56-dcca-41e2-b6bd-72ba3fa809be"
}

M12 - Reply to a thread

Request

Maximum of 1000 messages on a thread

Call Frequency
Recommended usage: Synchronous only - At each thread answer
Maximum usage: Synchronous only - At each thread answer

Path
thread_idstringrequired

The ID of the thread to reply to.

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)

List of attachments for the message
Maximum 50 across all threads of the same entity.
For example, for a given order, you can not have more than 50 attachments across all its threads.

message_inputobjectrequired

The message data

curl -i -X POST \
  'https://your-instance.mirakl.net/api/inbox/threads/{thread_id}/message?shop_id=0' \
  -H 'Content-Type: multipart/form-data' \
  -F files=string \
  -F 'message_input[body]=string' \
  -F 'message_input[to]=[object Object]' \
  -F 'message_input[topic][type]=string' \
  -F 'message_input[topic][value]=string'

Responses

Created

Bodyapplication/json
message_idstring

Id of the message

thread_idstring

Id of the thread

Response
application/json
{
  "message_id": "873f1cb5-a7a2-4e07-8e0e-12eb64e93ece",
  "thread_id": "702c3e56-dcca-41e2-b6bd-72ba3fa809be"
}

M13 - Download an attachment

Request

Call Frequency
Recommended usage: Synchronous only - At each message attachment download
Maximum usage: Synchronous only - At each message attachment download
Path
attachment_idstringrequired

The identifier of the attachment to retrieve.

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/inbox/threads/{attachment_id}/download?shop_id=0'

Responses

OK

Bodyapplication/octet-stream
string(binary)
Response
application/octet-stream
string

OR43 - Create a thread on an order

Request

Each message has a 10 Megabyte size limit, regardless of the number of attachments in the message.

Call Frequency
Recommended usage: At each new thread posted on an order
Maximum usage: At each new thread posted on an order
Path
order_idstringrequired

Identifier of the order on which the thread is created

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)

List of attachments for the first message of the thread

thread_inputobjectrequired

Thread content: body, topic, participants...

curl -i -X POST \
  'https://your-instance.mirakl.net/api/orders/{order_id}/threads?shop_id=0' \
  -H 'Content-Type: multipart/form-data' \
  -F files=string \
  -F 'thread_input[body]=string' \
  -F 'thread_input[to]=OPERATOR' \
  -F 'thread_input[topic][type]=FREE_TEXT' \
  -F 'thread_input[topic][value]=string'

Responses

Created

Bodyapplication/json
message_idstringrequired

Id of the first message created on the thread

thread_idstringrequired

Id of the created thread

Response
application/json
{
  "message_id": "00617ff1-7449-4574-a3a1-6fc256bf4d9b",
  "thread_id": "1f33b4f0-0cf8-4869-b148-e8e18b179770"
}

M01 - List messages linked to orders and offers⚠️ No Integration Allowed ⚠️Deprecated

Request

Returns messages received or sent to the shop. By default, returns only messages that are received by the shop.

Call Frequency
Recommended usage: Synchronous only - at each message list display
Maximum usage: Synchronous only - at each message list display
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)

Query
customer_idstring

Returns messages concerned by this customer_id

receivedstring
  • If TRUE: returns only messages received by shop.
  • If FALSE: returns only messages sent to the shop.
Default "TRUE"
Enum"TRUE""FALSE""ALL"
order_idstring

Order identifier

offer_idinteger(int64)

Offer identifier

start_datestring(date-time)

Start creation date for filtering

end_datestring(date-time)

End creation date for filtering

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"
visiblestringDeprecated
  • If TRUE: returns only the visible messages.
  • If FALSE: returns only the not visible messages.
Default "TRUE"
Enum"TRUE""FALSE""ALL"
curl -i -X GET \
  'https://your-instance.mirakl.net/api/messages?archived=TRUE&customer_id=string&end_date=2019-08-24T14%3A15%3A22Z&offer_id=0&order_id=string&read=TRUE&received=TRUE&shop_id=0&start_date=2019-08-24T14%3A15%3A22Z&visible=TRUE'

Responses

OK

Bodyapplication/json
messagesArray of objectsrequired

List of messages

total_countinteger(int32)required

Messages total count

Response
application/json
{
  "messages": [
    { … }
  ],
  "total_count": 1
}

OR42 - Post a message on an order⚠️ No Integration Allowed ⚠️Deprecated

Request

Maximum of 1000 messages on a thread

Call Frequency
Recommended usage: At each new message posted on an order
Maximum usage: At each new message posted on an order
Read More

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
bodystring[ 3 .. 50000 ] charactersrequired

Body of the message

document_idsArray of integers(int64)

Message's attachments. List of document ids already linked to the order. Use OR74 to upload new documents and OR72 to retrieve their ids. NB: If one of those document_id have already been linked to a previous message, it will be ignored.

subjectstring[ 3 .. 200 ] charactersrequired

Subject of the message

to_customerbooleanrequired

Boolean to indicate the message will be sent to the customer associated with the order.

to_operatorbooleanrequired

Boolean to indicate the message will be sent to the operator.

to_shopbooleanrequired

Boolean to indicate the message will be sent to the shop associated with the order

curl -i -X POST \
  'https://your-instance.mirakl.net/api/orders/{order_id}/messages?shop_id=0' \
  -H 'Content-Type: application/json' \
  -d '{
    "body": "I don'\''t receive my product! Could you please tell me when should i received it?",
    "document_ids": [
      "2032"
    ],
    "subject": "Item not received",
    "to_customer": false,
    "to_operator": false,
    "to_shop": true
  }'

Responses

Created

Bodyapplication/json
idinteger(int64)required

Identifier of the message created

Response
application/json
{
  "id": 2038
}

Offers

Operations

Orders

Operations

Incidents

Operations

Picklists

Operations

Promotions

Operations

Returns

Operations

Multiple shipments

Operations