# 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](/content/product/connect-channel-platform/getting-started/api-and-event-directory).
For the complete schemas of the requests and the responses, refer to the [REST APIs reference](/content/product/connect-channel-platform/rest/connect/openapi3).

## Base path and hosts

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](/content/product/connect-channel-platform/rest/connect/openapi3).

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](/content/product/connect-channel-platform/getting-started/environments) lists both, and the address of the authentication host.

## The `channel_id` parameter

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](/content/product/connect-channel-platform/getting-started/prerequisite-resources) for what else Mirakl provides before you start.

## Authentication

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](/content/product/connect-channel-platform/developer-guide/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](/content/product/connect-channel-platform/developer-guide/receiving-events).

## Synchronous and asynchronous operations

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](/content/product/connect-channel-platform/rest/connect/openapi3/catalog-configuration/configurechannelcatalog)
* [upsertProductType](/content/product/connect-channel-platform/rest/connect/openapi3/taxonomy/upsertproducttype)
* [updateStoreCatalogItems](/content/product/connect-channel-platform/rest/connect/openapi3/product-feedback/updatestorecatalogitems)


**One operation returns `202` without queueing anything.**
[createTaxonomyRule](/content/product/connect-channel-platform/rest/connect/openapi3/taxonomy/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](/content/product/connect-channel-platform/developer-guide/taxonomy#how-it-works) 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.

## Reading batch responses

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.

| Model | Behaviour | Operations |
|  --- | --- | --- |
| **All or nothing** | One invalid item rejects the whole request with a `400`, and Mirakl Connect applies nothing. | [upsertOrders](/content/product/connect-channel-platform/rest/connect/openapi3/orders/upsertorders) |
| **Partially successful** | A request that is syntactically valid returns `200`, **even if some or all the items failed**. The body reports the outcome for each item, so you must inspect it. | [upsertReturns](/content/product/connect-channel-platform/rest/connect/openapi3/returns/upsertreturns) |
| **Accepted, then filtered** | Mirakl Connect queues the request with a `202`, then silently ignores the items it does not recognize during the processing, without an error. | [updateStoreCatalogItems](/content/product/connect-channel-platform/rest/connect/openapi3/product-feedback/updatestorecatalogitems) |


## Error model

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.

### HTTP status codes

| Status | Meaning | What to do |
|  --- | --- | --- |
| `200` | Success, with a body. | Inspect the body, because individual items can still have failed. Read [Reading batch responses](#reading-batch-responses). |
| `201` | Mirakl Account created the channels or the stores. | Read the identifiers it returns, and store your mapping. |
| `202` | Accepted for asynchronous processing. | The work is queued, and it is not done yet. Read [Synchronous and asynchronous operations](#synchronous-and-asynchronous-operations). |
| `204` | Success, with no body. | Treat it as applied, subject to the `channel_updated_at` guard. Read [Calls you make: upserts are idempotent by design](/content/product/connect-channel-platform/developer-guide/best-practices#calls-you-make-upserts-are-idempotent-by-design). |
| `400` | Invalid request, such as a bad payload, an invalid field, or an invalid transition of state. | Fix the request, and do not retry it unchanged. |
| `401` | The token is missing, expired, or invalid. | Refresh the token and retry once. Read [Authorization](/content/product/connect-channel-platform/developer-guide/authorization). |
| `403` | The token is valid, but it misses the required scope. | This is a problem of authorization, so adjust the entitlements and do not refresh. |
| `404` | Mirakl Connect does not know a referenced resource, such as a channel, a store, an action, or an order. | Check the identifiers. It often means that the referenced entity was not synchronized first. |
| `410` | The consent token of the store import is expired, already used, or unknown. | Do not retry. The seller restarts the consent process. Read [The token](/content/product/connect-channel-platform/developer-guide/channel-authorization#the-token). |
| `429` | You exceeded the call frequency of the operation. | Wait for the delay of the `Retry-After` header, then retry. Read [Call frequency](#call-frequency--rate-limiting). |
| `500` | Server error. | It is transient, so retry with backoff. |


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.

### Error body shape

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

```json
{
  "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.


## Call frequency / Rate Limiting

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](/content/product/connect-channel-platform/developer-guide/best-practices#retries-and-backoff).

## Related pages

* [Authorization](/content/product/connect-channel-platform/developer-guide/authorization): how to obtain, present, and refresh the access token, and the model of the scopes.
* [Receiving events](/content/product/connect-channel-platform/developer-guide/receiving-events): the counterpart to this page, for the events you receive.
* [Best practices](/content/product/connect-channel-platform/developer-guide/best-practices): idempotency, ordering, retries and backoff, and the observability.
* [Environments](/content/product/connect-channel-platform/getting-started/environments): the test and production addresses of each host.
* [API and event directory](/content/product/connect-channel-platform/getting-started/api-and-event-directory): what each operation is for, grouped by business domain.