Merchant Center API

Learn about the Merchant Center API and how it helps you connect to commercetools APIs.

Customizations need to fetch data from different Composable Commerce APIs. For example, an application might fetch channel information or update product data.

Accessing Composable Commerce APIs requires authentication. For security reasons, client-side applications cannot be trusted with sensitive credentials, which makes it difficult to connect to an API directly from the browser.

To access these APIs, the Merchant Center provides an HTTP API that handles authentication and authorization. You can consider this like an API Gateway. Therefore, customizations use the Merchant Center API to make requests to the Composable Commerce APIs. The method in which you select the API in your requests depends on the API Gateway endpoints.

Cloud Regions

Composable Commerce is available in multiple cloud Regions. These Regions are isolated from each other and no data is transferred between them. Subsequently, each Composable Commerce account is valid for only a single Region.

To use more than one Region, you must sign up for each Region separately. If you need help deciding the Region for your Project, please contact commercetools support.

Hostnames

The Merchant Center and the Merchant Center API Gateway are available in the same cloud Regions where Composable Commerce runs.

All hostnames are subdomains of commercetools.com and follow a specific naming format, including the cloud provider, the cloud Region, and the Merchant Center service name.

https://{mcService}.{region}.{cloudProvider}.commercetools.com

mcService: the Merchant Center service, either mc for the frontend application, or mc-api for the API Gateway.
region: the Region of the cloud provider (see the following table).
cloudProvider: the cloud provider, either gcp or aws.

Available regions

Cloud Region	Merchant Center API Gateway hostname
Australia (Google Cloud, Sydney)	`mc-api.australia-southeast1.gcp.commercetools.com`
Europe (Google Cloud, Belgium)	`mc-api.europe-west1.gcp.commercetools.com`
Europe (AWS, Frankfurt)	`mc-api.eu-central-1.aws.commercetools.com`
North America (Google Cloud, Iowa)	`mc-api.us-central1.gcp.commercetools.com`
North America (AWS, Ohio)	`mc-api.us-east-2.aws.commercetools.com`

Cloud identifiers

To make it easier to reference the Merchant Center API URL, for example in your Custom Application config or Custom View config, each cloud Region maps to an identifier.

Cloud Region	Cloud identifier
Australia (Google Cloud, Sydney)	`gcp-au`
Europe (Google Cloud, Belgium)	`gcp-eu`
Europe (AWS, Frankfurt)	`aws-eu`
North America (Google Cloud, Iowa)	`gcp-us`
North America (AWS, Ohio)	`aws-us`

Authentication

The Merchant Center API is protected by a session token via the HTTP Cookie header, which is set only for <cloud-region>.commercetools.com domains.

In the browser, the session token is stored in a secure cookie named mcAccessToken and is valid for 30 days.

Cookie: mcAccessToken=<jwt>

Sending the cookie to the Merchant Center API is pre-configured in the built-in HTTP clients (see Data fetching), by using the credentials: "include" option of the Fetch API.

In local development, the authentication process differs by using an OpenID Connect (OIDC) login workflow. The session token is stored in the browser's session storage and sent to the Merchant Center API via the Authorization HTTP header.

Authorization: Bearer <token>

The token is accessible from the session storage:

window.sessionStorage.getItem('sessionToken');

Obtaining a session token

The session token mcAccessToken is granted upon user login and is stored in a secure cookie in the browser.

The Merchant Center API provides two endpoints for authenticating a user:

/tokens: for normal login using email and password.
/tokens/sso: for login using an idToken from an SSO workflow (see Single sign-on).

When you develop a customization, all authentication logic is handled implicitly and no further setup is needed from your side.

HTTP headers

To access the Merchant Center API, you must include the following HTTP headers in the HTTP request:

Header	Required	Description
`Accept`	Required	Set it to `application/json`.
`Authorization`	Required only in development.	For more information, see Authentication.
`Content-Type`	Required when sending a payload.	Set it to `application/json` when sending JSON data.
`X-Application-ID`	Required only for Custom Applications.	The identifier of the Custom Application. Set it to `<applicationId>:<entryPointUriPath>`. See Custom Application config for details.
`X-Custom-View-ID`	Required only for Custom Views.	The identifier of the Custom View.
`X-Correlation-ID`	Recommended	The unique identifier of the request. Set it to `mc/<projectKey>/<userId>/<randomHash>`. The `randomHash` can be generated using the uuid library.
`X-Project-Key`	Required	The key of the commercetools Project currently being used by the customization. Validation is performed by the Merchant Center API Gateway. The project key can be retrieved from the Application or Custom View context.
`X-User-Agent`	Recommended	Set it to a custom user-agent that identifies the HTTP client, for example using the HTTP user-agent library.

API Gateway endpoints

The Merchant Center API primarily acts as an API Gateway with the following responsibilities:

verifying the user session.
routing the request to the correct route handler, specific to the targeted API.
ensures that requests to the target APIs are properly authenticated and authorized (OAuth scopes and user permissions).

The following API endpoints are available:

/graphql: used for GraphQL requests.
/proxy/*: used for REST requests.

/graphql

The Merchant Center API exposes a single /graphql endpoint.

https://mc-api.<cloud-region>.commercetools.com/graphql

However, there are multiple target GraphQL APIs that customizations can use. To instruct the API Gateway to target the correct API, you need to provide a special HTTP header: X-Graphql-Target.

The following targets are available:

ctp: proxies requests to the Composable Commerce GraphQL API.
change-history: proxies requests to the Composable Commerce Change History API.
mc: proxies requests to the Merchant Center GraphQL API.

For most cases, you should only need to use the Composable Commerce GraphQL API.

To learn more, see Data fetching.

/proxy/:target/*

The Merchant Center API exposes multiple proxy endpoints to target a specific REST API.

https://mc-api.<cloud-region>.commercetools.com/proxy/*

The following proxy endpoints are available:

/proxy/ctp/*: proxies requests to the Composable Commerce HTTP API.
/proxy/import/*: proxies requests to the Import API.
/proxy/forward-to: see Integrate with your own API.

The proxy endpoints work by acting as "prefixes" to the actual endpoint path of the targeted API.

For example:

// To use the Orders API, you would send a request to:
https://api.europe-west1.gcp.commercetools.com
  /:projectKey/orders

// The same results would be achieved using the API Gateway like:
https://mc-api.europe-west1.gcp.commercetools.com
  /proxy/ctp
  /:projectKey/orders