Products

Mirakl Platform (MMP)

Rest Front APIs

PM11 - Get the product attribute configuration

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 with OAuth 2.0

You must authenticate with a bearer token that can be generated from your Mirakl Platform back office. Refer to Generating Front API integration access tokens documentation page for more information.

Legacy authentication (deprecated)

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

Important note: This authentication mode is deprecated and is intended to be discontinued. We highly encourage to use one of the two OAuth 2.0 modes cited above.

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

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/

Platform Settings

Operations

Invoicing and Accounting

Operations

Products

Operations

H11 - List Catalog categories (parents and children) related to a Catalog category

Request

Call Frequency

Recommended usage: Every hour

Maximum usage: Every hour

Query

hierarchystring

Catalog category code

max_levelinteger(int32)

Number of children catalog category levels to retrieve. If not specified, all child catalog categories are retrieved

curl -i -X GET \
  'https://your-instance.mirakl.net/api/hierarchies?hierarchy=string&max_level=0'

Responses

Bodyapplication/json

hierarchiesArray of objectsrequired

List of hierarchies

Response

application/json

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

P31 - Get products for a list of product references

Request

Note: this resource returns 100 products maximum
Results are sorted by product sku asc, then by product identifier type asc and then by product identifier asc

Call Frequency

Recommended usage: At each product page display

Maximum usage: At each product page display

Localization

This resource supports locale parameter (see documentation)

Localized output fields will be highlighted with an icon:

Query

product_referencesstringrequired

List of the product's identifiers with type, (structure: "product_references=<productIdType>|<productId>,<productIdType>|<productId>, ...") where accepted <productIdType> are operator’s product references, like EAN or UPC for example. Note that SHOP_SKU or SKU are invalid <productIdType> for this API.

productsstringDeprecated

List of the product's identifiers with type, (structure: "products=<productId>|<productIdType>,<productId>|<productIdType>, ...") where accepted <productIdType> are operator’s product references, like EAN or UPC for example. Note that SHOP_SKU or SKU are invalid <productIdType> for this API.

curl -i -X GET \
  'https://your-instance.mirakl.net/api/products?product_references=string&products=string'

Responses

Bodyapplication/json

productsArray of objectsrequired

Products

total_countinteger(int32)Deprecatedrequired

Total count

Response

application/json

{
  "products": [
    { … }
  ]
}

P41 - Import products to the operator information system

Request

Returns the import identifier to track the status of the import

Call Frequency

Recommended usage: Every hour, for each seller

Maximum usage: Every 15 minutes, for each seller

More context

Bodymultipart/form-data

filestring(binary)required

Import file (CSV or XML or XLSX) to upload. Use multipart/form-data with name file

operator_formatboolean

Force the use of the operator product format

Default false

shopinteger(int64)required

Shop identifier

curl -i -X POST \
  https://your-instance.mirakl.net/api/products/imports \
  -H 'Content-Type: multipart/form-data' \
  -F file=string \
  -F operator_format=true \
  -F shop=0

Responses

Created

Headers

Locationany

Pre-calculated URL to call to get the import status

Bodyapplication/json

import_idinteger(int64)required

Import identifier

Response

application/json

{
  "import_id": 2035
}

P51 - Get information about product import statuses

Request

If the last_request_date param is not set the api returns all product imports.

Call Frequency

Recommended usage: Every 5 minutes

Maximum usage: Once per minute

More context

Pagination

This resource supports offset pagination (see documentation)

Sort fields

sort field can have the following values:

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

Query

last_request_datestring(date-time)

Return only product imports that have changed since this date

statusstring

Product import status. One of CANCELLED, WAITING, RUNNING, SENT, COMPLETE, FAILED

has_transformed_fileboolean

If true returns only product import trackings with transformed file

shop_idinteger(int64)required

Shop identifier

curl -i -X GET \
  'https://your-instance.mirakl.net/api/products/imports?has_transformed_file=true&last_request_date=2019-08-24T14%3A15%3A22Z&shop_id=0&status=string'

Responses

Bodyapplication/json

product_import_trackingsArray of objects

List of product import status information

total_countinteger(int32)required

Total count of product import status information

Response

application/json

{
  "product_import_trackings": [
    { … },
    { … }
  ],
  "total_count": 2
}

P42 - Get the import status for a product import

Request

Call Frequency

Recommended usage: Once per minute until getting the import final status

Maximum usage: Once per minute

Path

importinteger(int64)required

Import identifier

curl -i -X GET \
  'https://your-instance.mirakl.net/api/products/imports/{import}'

Responses

Bodyapplication/json

date_createdstring(date-time)required

Import creation date

has_error_reportbooleanrequired

Returns true if error report is available. Value is filled when the import is completed

has_new_product_reportbooleanrequired

Returns true if new product report is available. Value is filled when the import is completed

has_transformation_error_reportboolean

Returns true if transformation error report is available. Value is filled when the import is completed

has_transformed_filebooleanrequired

Returns true if transformed file is available. Value is filled when the import is completed

import_idinteger(int64)required

Import identifier

import_statusstringrequired

Import status

Enum"TRANSFORMATION_WAITING""TRANSFORMATION_RUNNING""TRANSFORMATION_FAILED""WAITING""RUNNING""SENT""COMPLETE""CANCELLED""FAILED"

integration_detailsobject

Integration details

reason_statusstring

A message explaining the reason of the import status, if relevant

shop_idinteger(int64)required

Shop identifier

transform_lines_in_errorinteger(int64)required

Total count of transformed lines in error

transform_lines_in_successinteger(int64)required

Total count of transformed lines in success

transform_lines_readinteger(int64)required

Total count of transformed lines read

transform_lines_with_warninginteger(int64)required

Total count of transformed lines with warning

Response

application/json

{
  "date_created": "2019-04-05T12:56:21Z",
  "has_error_report": false,
  "has_new_product_report": false,
  "has_transformation_error_report": false,
  "has_transformed_file": true,
  "import_id": 2005,
  "import_status": "SENT",
  "shop_id": 2000,
  "transform_lines_in_error": 0,
  "transform_lines_in_success": 1,
  "transform_lines_read": 1,
  "transform_lines_with_warning": 0
}

P44 - Get the error report file for a product import ("Non-integrated products report")

Request

This API returns either a CSV file (MCM enabled) or a file in a format defined by the Marketplace operator (MCM disabled).

Call Frequency

Recommended usage: Each time an error report is needed

Maximum usage: Each time an error report is needed

More context

Path

importinteger(int64)required

Import identifier

curl -i -X GET \
  'https://your-instance.mirakl.net/api/products/imports/{import}/error_report'

Responses

Bodyapplication/octet-stream

string(binary)

Response

application/octet-stream

string

P45 - Get the product integration report file for a product import ("Added products report")

Request

This API returns either a CSV file (MCM enabled) or a file in a format defined by the Marketplace operator (MCM disabled).

Call Frequency

Recommended usage: Each time an integration report is needed

Maximum usage: Each time an integration report is needed

Path

importinteger(int64)required

Import identifier

curl -i -X GET \
  'https://your-instance.mirakl.net/api/products/imports/{import}/new_product_report'

Responses

Bodyapplication/octet-stream

string(binary)

Response

application/octet-stream

string

P46 - Get the transformed file for a product import ("File in marketplace format")

Request

This API returns a CSV file.

Call Frequency

Recommended usage: Each time a transformed file is available

Maximum usage: Each time a transformed file is available

Path

importinteger(int64)required

Import identifier

curl -i -X GET \
  'https://your-instance.mirakl.net/api/products/imports/{import}/transformed_file'

Responses

Bodytext/csv

string(binary)

Response

text/csv

string

P47 - Get the transformation error report file for a product import ("Source file error report")

Request

This API returns a CSV, XLSX or XML file, depending on the file format provided by the seller.

Call Frequency

Recommended usage: Each time an error report is needed

Maximum usage: Each time an error report is needed

Path

importinteger(int64)required

Import identifier

curl -i -X GET \
  'https://your-instance.mirakl.net/api/products/imports/{import}/transformation_error_report'

Responses

Bodyapplication/octet-stream

string(binary)

Response

application/octet-stream

string

PM11 - Get the product attribute configuration

Request

Retrieves all attributes for parents and children of the requested hierarchy

Call Frequency

Recommended usage: Every hour

Maximum usage: Every hour

Query

hierarchystring

Code of the hierarchy (category) for which to retrieve the attributes. If not specified, all attributes are retrieved.

max_levelinteger(int32)

Number of children hierarchy (category) levels to retrieve. If not specified, attributes from all children hierarchies are retrieved.

channelsArray of stringsunique

List of channel codes

with_rolesboolean

Set to "true" to get only the attributes that have roles.

Default false

curl -i -X GET \
  'https://your-instance.mirakl.net/api/products/attributes?channels=string&hierarchy=string&max_level=0&with_roles=false'

Responses

Export success

Body

attributesArray of objectsrequired

List of attributes

Response

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

VL11 - Get information about operator's value lists

Request

Call Frequency

Recommended usage: Every hour

Maximum usage: Every hour

Query

codestring

The operator's values list code. If not specified, all values lists are retrieved

curl -i -X GET \
  'https://your-instance.mirakl.net/api/values_lists?code=string'

Responses

Bodyapplication/json

values_listsArray of objects

List of values list

Response

application/json

{
  "values_lists": [
    { … }
  ]
}

Messages

Operations

Offers

Operations

Orders

Operations

Picklists

Operations

Promotions

Operations

Returns

Operations

Stores

Operations

Multiple shipments

Operations