This is the new documentation of Custom Applications. You can still visit the legacy documentation during the migration from Project-level Custom Applications.


Merchant Center API

Custom Applications need to fetch data from different APIs in the commercetools Platform. Examples are fetching channel information or updating product data.

Accessing these API requires some sort of authentication mechanism. 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 solve these issues, the Merchant Center provides an HTTP API that handles authentication and authorization to all commercetools Platform APIs. You can think about it as an API Gateway.

Therefore, Custom Applications use the Merchant Center API to make requests to one of the commercetools Platform APIs. The way you select the API in your requests depends on the API Gateway endpoints.

Merchant Center API
Merchant Center API

Cloud Regions

The commercetools Platform is available in multiple cloud Regions. These Regions are completely isolated from each other and no data is transferred between them.

Platform accounts created for one Region are not valid for the other Regions. A signup is required for each Region individually. In case you need advice in which Region your Project should be located, please contact commercetools support.


The Merchant Center and the Merchant Center API Gateway are available at the same cloud Regions where the commercetools Platform runs.

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

  • mcService: for the Merchant Center frontend the value is mc, for the Merchant Center API Gateway the value is mc-api.
  • region: the Region of the cloud provider, see table below.
  • cloudProvider: the cloud provider, either gcp or aws.
Cloud RegionMerchant Center API Gateway hostname
Australia (Google Cloud, Sydney)
Europe (Google Cloud, Belgium)
Europe (AWS, Frankfurt)
North America (Google Cloud, Iowa)
North America (AWS, Ohio)

Cloud Identifiers

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

Cloud RegionCloud 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


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

In the browser, the session token is stored in a secure cookie named mcAccessToken.

Cookie: mcAccessToken=<jwt>

Sending the cookie to the Merchant Center API is already 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 is handled a bit differently using a OpenID Connect (OIDC) login workflow. The session token is stored in sessionStorage and sent to the Merchant Center API via Authentication HTTP header.

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 Custom Application all authentication logic is handled implicitly and you don't need to worry about it.

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.
  • Making sure that requests to the targeted APIs are properly authenticated and authorized (OAuth Scopes and user permissions).

As for the API endpoints available to be used to target the correct API, they are grouped in two categories:

  • /graphql: For GraphQL requests.
  • /proxy/*: For REST requests.


The Merchant Center API exposes a single /graphql endpoint.


However, there are multiple target GraphQL APIs that Custom Applications 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:

Normally you would only need to use the official commercetools Platform GraphQL API as other APIs are mostly for internal usage and not documented.

To learn more how to use the target values, check out the Data Fetching documentation for developing Custom Applications.


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


The following proxy endpoints are available:

The way the proxy endpoints work is that they act as "prefixes" to the actual endpoint path of the targeted API. For example:

// To use the Orders API, you would send a request to:
// The same results would be achieved using the API Gateway like: