Skip to main content

​
Overview

Once Commercetools is connected, the Dema Agent can query orders, products, customers, inventory, and categories from your Commercetools project. Useful for bringing composable commerce data into a Dema analysis.

​
Prerequisites

  • A Commercetools project you have admin access to.
  • Permission to create API Clients in the Commercetools Merchant Center.
  • Your project’s region — it appears in the Auth URL shown when you create the API Client (for example europe-west1.gcp, us-central1.gcp, or an AWS region like eu-central-1.aws).
Commercetools uses long-lived API credentials rather than an interactive login. You create an API Client in Merchant Center and paste its credentials into Dema.

​
Connect Commercetools

1

Create an API Client in Merchant Center

  1. Open Merchant Center and go to Settings → Developer settings → API clients.
  2. Click Create new API client.
  3. Give it a recognizable name such as Dema Agent.
  4. Under Scopes, select the scopes listed under Scopes Dema requests below. You can scope access to specific stores if you only want Dema to see part of the project.
  5. Click Create New API Client.
2

Copy the credentials

Merchant Center shows the credentials only once. Copy the following values:
  • Client ID
  • Secret
  • Auth URL (for example https://auth.europe-west1.gcp.commercetools.com/oauth/token). This is the value you paste into Dema as the Token URL.
3

Paste the credentials into Dema

In Dema, go to Agents → Settings → Integrations, find Commercetools, and click Connect. Enter:
  • Client ID
  • Client secret
  • Token URL (the auth URL from the previous step)
Click Add. Dema verifies the credentials and marks the integration as Active.
You do not need to enter a project key. Dema reads the project key from the scopes you granted the API Client (for example view_orders:my-project-key) during the first token exchange.

​
Scopes Dema requests

Dema honors whichever scopes you assign to the API Client. For typical agent use, grant at least: Replace {projectKey} with your project’s key. When you select scopes in Merchant Center, they apply to the project the API Client belongs to — you don’t type the key by hand.
There is no separate inventory scope. view_products:{projectKey} also grants read access to inventory entries (stock levels).

​
Rotating the credentials

Commercetools API Client secrets do not expire, but a client is immutable once created — you cannot change its scopes or regenerate its secret. To rotate:
  1. In Merchant Center, create a new API Client with the same scopes.
  2. In Dema, click Reconnect on the Commercetools integration card and enter the new Client ID, Client secret, and Token URL.
  3. Delete the old API Client in Merchant Center.
Rotate periodically, and immediately if you suspect the secret was exposed.

​
Troubleshooting

  • Dema says the token URL is invalid. The auth URL must be HTTPS and must end with .commercetools.com. Use the URL shown in Merchant Center for your region, not a hand-written value.
  • Dema cannot authenticate. Double-check the client secret. Merchant Center only shows it once, so if you lost it, create a new API Client and paste the new credentials.
  • Missing scopes. If the agent reports it cannot see a resource, add the matching scope to the API Client in Merchant Center and reconnect in Dema.

​
Additional resources