This is the legacy documentation of Project-level Custom Applications, which is in maintenance mode. Visit the new documentation for Org-level Custom Applications.


API Gateway

Merchant Center applications need to fetch data from different sources in the commercetools platform. A Custom Application might need to access channel, or product information, role, and permission settings, and more. Each of these data sources is exposed as an API, and each of these APIs requires an authentication mechanism.

However, for security reasons, client-side applications cannot be trusted with sensitive credentials, which makes it difficult to connect to an API directly from a browser.

To solve these issues, the Merchant Center provides an API Gateway, which proxies requests to underlying APIs. Requests made through the proxy will be authenticated with the correct authentication mechanism specific to the targeted API. This way, a client-side application only needs to authenticate to the Merchant Center API Gateway without needing to store credentials for the targeted APIs.

Architecture overview


For security reasons, it is recommended that Custom Applications use the API Gateway to access the commercetools APIs. See Proxy Endpoints.

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 front-end 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 (gcp, aws, etc.).
Cloud regionMerchant Center API Gateway hostname
North America (Google Cloud, Iowa)
North America (AWS, Ohio)
Europe (Google Cloud, Belgium)
Europe (AWS, Frankfurt)
Australia (Google Cloud, Sydney)

Legacy hostnames

Any hostname that does not follow the new naming format is considered a legacy hostname.

Legacy hostname will still be available for the time being, but it is highly recommended to switch to the new hostnames as soon as possible.

Currently the following hostnames are considered legacy:

Legacy hostnameNew hostname