# 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 platform APIs. For example, an application might fetch channel information or update product data.

Accessing the 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 platform APIs. The method in which you select the API in your requests depends on the [API Gateway endpoints](/merchant-center-customizations/concepts/merchant-center-api.md#api-gateway-endpoints).

```mermaid
flowchart TD
	subgraph mcApi [Merchant Center API]
		Authentication
		Router{Router} -->|/graphql| Proxy
		Router{Router} -->|/proxy/*| Proxy
		Authentication --> Router
		Proxy <--> Authorization
	end
	subgraph coco [commercetools API platform]
		Api1[API]
		Api2[API]
		Api3[API]
		CoCoAuth[Auth]
	end

	Proxy --> Api1
	Proxy --> Api2
	Proxy --> Api3
	Authorization <-->|access token| CoCoAuth
```

## Cloud Regions

The commerce APIs are available in [multiple cloud Regions](/api/general-concepts.md#regions).
These Regions are isolated from each other and no data is transferred between them.

To use more than one Region, you must [sign up](/api/getting-started/initial-setup.md) for each Region separately. If you need help deciding the Region for your Project, contact [commercetools support](https://support.commercetools.com/).

### Hostnames

The Merchant Center and the Merchant Center API Gateway are available in the same cloud Regions as the commerce APIs.

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](/merchant-center-customizations/tooling-and-configuration/custom-application-config.md#cloudidentifier) or [Custom View config](/merchant-center-customizations/tooling-and-configuration/custom-view-config.md#cloudidentifier), 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.

```
Cookie: mcAccessToken=<jwt>
```

In the browser, the session token is stored in a secure cookie named `mcAccessToken`. The session token for the Merchant Center is issued automatically when there is a valid user session from our [Identity authentication service](/docs/identity/overview.md).

Sending the cookie to the Merchant Center API is pre-configured in the built-in HTTP clients (see [Data fetching](/merchant-center-customizations/development/data-fetching.md)), by using the `credentials: "include"` option of the [Fetch API](https://fetch.spec.whatwg.org/).

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:

```js
window.sessionStorage.getItem('sessionToken'); 
```

## 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](/merchant-center-customizations/concepts/merchant-center-api.md#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](/merchant-center-customizations/tooling-and-configuration/custom-application-config.md) 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](https://www.npmjs.com/package/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](/merchant-center-customizations/tooling-and-configuration/commercetools-frontend-application-shell-connectors.md#application-and-custom-view-contexts). |
| `X-User-Agent` | Recommended | Set it to a custom user-agent that identifies the HTTP client, for example using the [HTTP user-agent](https://www.npmjs.com/package/@commercetools/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](/merchant-center-customizations/concepts/oauth-scopes-and-user-permissions.md)).

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 [commerce GraphQL API](/api/graphql.md).
- `change-history`: proxies requests to the [Change History API](/api/history/change-history.md).
- `mc`: proxies requests to the Merchant Center GraphQL API.

For most cases, you should only need to use the [commerce GraphQL API](/api/graphql.md).

To learn more, see [Data fetching](/merchant-center-customizations/development/data-fetching.md).

### /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 [HTTP API](/api).
- `/proxy/import/*`: proxies requests to the [Import API](/api/import-export/overview.md).
- `/proxy/forward-to`: see [Integrate with your own API](/merchant-center-customizations/concepts/integrate-with-your-own-api.md).

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

For example:

```js highlightLines="6,7"
// 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
```

## Related

For more information on what to do next, we recommend the following sections:

- **[Data fetching](/merchant-center-customizations/development/data-fetching.md)**

  Learn more about fetching data via Merchant Center API.

## Related pages

- [Area overview page with navigation](/merchant-center-customizations.md)
- [Previous page: Merchant Center Proxy Router](/merchant-center-customizations/concepts/merchant-center-proxy-router.md)
- [Next page: Integrate with your own API](/merchant-center-customizations/concepts/integrate-with-your-own-api.md)