Merchant Center API

Learn about the Merchant Center API and how to use it within your customizations.

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.

Composable Commerce accounts are valid for a single Region only. To use more than one Region, you must signup for each Region separately.

If you need help to decide in which Region your Project should be located, 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`
China (AWS, Ningxia)	`mc-api.cn-northwest-1.aws.commercetools.cn`

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-fra`
North America (Google Cloud, Iowa)	`gcp-us`
North America (AWS, Ohio)	`aws-ohio`
China (AWS, Ningxia)	`aws-cn`

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 you don't need to worry about it.

HTTP headers

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

Accept (required): set it to application/json.
Authorization (required only in development): 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 Application config for applicationId and entryPointUriPath).
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. The Merchant Center API Gateway will perform a validation check to ensure that the user has access to the Project, then forward the request to your server only if the check was successful.
The project key can be retrieved from the Application context.
X-User-Agent (recommended): set it to a custom user-agent identifying 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.

Generally, 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 Export 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