Calling the APIs

This page covers the mechanics that every call you make shares:

• where the APIs are served,
• the identifier they are scoped by,
• how they are authenticated,
• how to read the response you get back.

It applies to all the calls, whatever domain they belong to.

For what each operation does, and which business domain it serves, refer to the API and event directory. For the complete schemas of the requests and the responses, refer to the REST APIs reference.

The REST APIs are served over HTTPS, under the base path /api/channel-platform. Take the full path of each operation from its entry in the REST APIs reference.

The calls are split across two hosts, by the data they carry:

• Mirakl Connect serves most integrator operations: the orders, the returns, the carriers, the order documents, the catalog configuration, the taxonomy, and a store's business information.
• Mirakl Account serves the account data, which is the operations that create and update a store.

Each host has a test address and a production address. Environments lists both, and the address of the authentication host.

Most operations are scoped by a channel_id, the identifier of your channel in Mirakl Connect. It appears as a path parameter:

POST /api/channel-platform/v1/catalog-configuration/channels/{channel_id}

Mirakl generates this identifier when it registers your channel, and the partner team provides it to you. Your connector does not create it. Store it in the configuration of your connector, and pass it on every call that requires it. You also see it on the events you receive, which is what lets you correlate the two directions. Refer to Get access for what else Mirakl provides before you start.

Every call carries an OAuth2 access token, as an Authorization: Bearer header. You obtain the token with the client credentials Mirakl issues you.

Tokens carry fine-grained scopes, one for each operation, and each operation declares the scope it requires:

• a 401 means that the token was missing or expired,
• a 403 means that the token was valid but lacked the scope.

Authorization documents the full mechanism: how to obtain a token, how to cache it, how to refresh it, and the model of the scopes.

The events you receive carry no token of their own, because Mirakl Connect publishes them to the queue or the topic you own. Refer to Receiving events.

Operations fall into two groups, and the group decides what a success response means.

Asynchronous: the catalog, taxonomy, and feedback operations. These return 202 Accepted, which means that Mirakl Connect queued the request and has not applied it yet. A 202 is not a confirmation that the change took effect. The validation happens during the background processing, so a problem in the content surfaces later, not in the response.

Three operations are asynchronous, and each one returns 202 on success:

• configureChannelCatalog
• upsertProductType
• updateStoreCatalogItems

One operation returns 202 without queueing anything. createTaxonomyRule validates and stores the rules during the request. A malformed rule therefore fails the call with a 400, and a 202 means that the rules are stored. Read Taxonomy for how it pairs with upsertProductType.

Synchronous: the store, order, return, document, and carrier operations. Mirakl Connect applies these before it returns the response, so a 200 or a 204 means that the work is done. Everything that is not in the list above is synchronous.

Do not treat the two groups the same way when you build your connector. An asynchronous operation needs no immediate follow-up read, but it also gives you no immediate confirmation. You therefore observe its effects through the events and the feedback that follow, not through its own response.

Several operations accept a batch, and they do not all report a failure the same way. Check which model an operation uses before you write its error handling, because the HTTP status alone does not always tell you that every item was accepted.

The REST APIs share a consistent error body. This shape comes from the API contract. Treat it as the general shape, and confirm the precise codes and the nuances of each operation in the reference entry of that operation.

The two hosts do not return the same set. The 201 and the 410 belong to the Account Channel Platform operations, which define no 500. Take the statuses each operation declares from its reference entry.

An error response returns a JSON object with a machine-readable code, a message a human can read, and optional detail for each field:

{
  "code": "DATA_NOT_FOUND",
  "message": "An error occurred while processing your request",
  "errors": [
    {
      "message": "An error occurred while processing your request: id is null",
      "field": "input.account.id"
    }
  ],
  "extensions": {}
}

• code: an immutable, machine-readable error code, such as DATA_NOT_FOUND. Branch your error handling on code, never on message.
• message: a description a human can read. The contract explicitly documents it as subject to change, so log it, but do not parse it and do not match on it.
• errors[]: optional detail for each item. Each entry carries a message, and optionally a field, which is a JSON path such as input.account.id that pinpoints the field at fault, and its own extensions.
• extensions: a free-form map of additional context about the error.

The reference entry of each endpoint publishes a recommended call frequency and a maximum call frequency. Throttle your calls to the recommended frequency, and never exceed the maximum one.

When you exceed a limit, Mirakl Connect rejects the call with a 429 response and a Retry-After header, in seconds. Wait for that delay before you send the call again.

Back off exponentially on any 5xx. Refer to Retries and backoff.

• Authorization: how to obtain, present, and refresh the access token, and the model of the scopes.
• Receiving events: the counterpart to this page, for the events you receive.
• Best practices: idempotency, ordering, retries and backoff, and the observability.
• Environments: the test and production addresses of each host.
• API and event directory: what each operation is for, grouped by business domain.