How to Generate commercetools API Credentials for Pimcore
Before Pimcore 12 can read a single product out of your commercetools project — or push one back — it needs an API client. Everything else in a catalog sync is configuration. The credentials are the part that decides whether the connection works at all.
This guide covers only that: creating the API client in the commercetools Merchant Center, picking the right OAuth scopes, understanding the six values commercetools hands you, and getting them into Pimcore. No mapping, no jobs — just the credentials. If you already have a working API client and want the full sync walkthrough, read How to Connect Pimcore 12 to commercetools.
First: commercetools Has No “API Key”
If you are coming from Shopify, WooCommerce or Magento, you are probably looking for a single token to paste into a field. commercetools does not work that way.
commercetools uses the standard OAuth2 client credentials flow. You create an API client, which gives you a Client ID and a Client Secret. Those are not the token — they are exchanged for a short-lived bearer token, which is what actually gets sent on every API call. The token expires after 48 hours by default, and whatever is calling the API is expected to fetch a new one when it does.
That sounds like more work, and for a hand-rolled integration it is. For the Pimcore commercetools Connector it is less: the connector performs the token exchange itself, caches the token, and refreshes it before it expires. You store the Client ID and Secret once and never think about tokens again — no expiry to babysit, no credential to re-paste every two days.
Step 1 — Create the API Client in the Merchant Center
The full official walkthrough is Create an API client in the commercetools docs. Condensed:
- Log in to the commercetools Merchant Center for the region your project lives in.
- Select the project you want Pimcore to sync with. Credentials are per project, not per account.
- Go to Settings → Developer settings.
- Open the API clients tab and click Create new API client.
- Give it a name you will recognise in six months — Pimcore Catalog Sync beats test client 3. The name appears in the API client list and is how you decide later which one is safe to revoke.
- Choose the scopes. This is the part worth slowing down for — see the next section.
- Click Create API client.
Step 2 — Which Scopes Does a Pimcore Catalog Sync Need?
The Merchant Center offers scope templates, and the tempting one is Admin client — complete access to everything in the project. Do not use it for a catalog sync. An Admin client can delete your orders, edit your customers and change your project settings, none of which a product sync has any business doing. commercetools’ own getting-started guide recommends keeping scopes to the minimum necessary.
Here is what a Pimcore sync actually needs:
| What you want to sync | Scope | Needed for |
|---|---|---|
| Products and variants | view_products | Import into Pimcore |
| Product types (families) and their attribute definitions | view_product_types | Import |
| The category tree | view_categories | Import |
| Products and variants, written back | manage_products | Export from Pimcore |
| Product types, written back | manage_product_types | Export |
| Categories, written back | manage_categories | Export |
Two useful shortcuts. If you only ever pull commercetools into Pimcore, grant the three view_ scopes and stop — a read-only client cannot damage your catalog no matter what goes wrong, which makes the first weeks of a project far less nerve-wracking. If you sync both directions, the three manage_ scopes cover their view_ equivalents, so you do not need both.
Scopes carry the project key. A scope is not view_products; it is view_products:{projectKey}. So for a project keyed acme-eu the real scope string is:
view_products:acme-eu view_product_types:acme-eu view_categories:acme-eu
The Merchant Center adds the project key for you when you tick boxes in the UI. It matters when you type scopes by hand somewhere else — a scope without the project key suffix is rejected.
Full reference, if your setup needs something outside a catalog sync: commercetools OAuth scopes.
Step 3 — Save the Credentials. You Get One Chance
The moment you click Create API client, commercetools shows you a block of values. This block is displayed exactly once. Navigate away and the client secret is gone permanently — there is no reveal-again, no recovery, and your only option is to delete the client and create another.
Download the Environment Variables (.env) file the page offers, or copy the values into your password manager, before you do anything else. The file arrives named {projectKey}_{API client name}.env.
Six values come out, and this is what each of them is:
| Value | What it is |
|---|---|
| Project key | The identifier of the commercetools project itself, e.g. acme-eu. It is part of every API URL and part of every scope string. Not a secret. |
| Client ID | The username half of the credential. Not a secret, though there is no reason to publish it. |
| Secret | The password half. This is the one shown once. Treat it as a production password. |
| Scope | The exact space-separated scope string granted to this client, project key suffixes included. Useful to keep — it is the definitive record of what this client can do. |
| API URL | Where data requests go, e.g. https://api.europe-west1.gcp.commercetools.com. Region-specific. |
| Auth URL | Where the token exchange happens, e.g. https://auth.europe-west1.gcp.commercetools.com. Region-specific, and a different host from the API URL. |
If you want to see the exchange for yourself before involving Pimcore, this is the whole of it:
curl https://auth.europe-west1.gcp.commercetools.com/oauth/token -X POST \ --basic --user "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET" \ -d "grant_type=client_credentials&scope=view_products:acme-eu"
A working credential returns a bearer token with "expires_in": 172800 — 48 hours. A broken one returns 401, and the next section is about why that usually is not the password.
The Region Trap
This is the single most common reason a brand-new commercetools credential fails, and it wastes a surprising amount of time because the symptom lies to you.
commercetools runs fully isolated regions. A project in Belgium does not exist in Iowa. Accounts do not cross regions either — a Merchant Center login for one region is not valid in another. Point a perfectly good Client ID and Secret at the wrong region and you get 401 Unauthorized, exactly the same response you would get from a wrong password. People then rotate the secret, re-copy it carefully, create a second API client, and get the same 401 every time, because the credential was never the problem.
If a fresh credential returns 401, check the region before you touch the secret.
The regions and the host segment each one uses:
| Region | Host segment | API URL |
|---|---|---|
| Europe — Google Cloud, Belgium | europe-west1.gcp | https://api.europe-west1.gcp.commercetools.com |
| Europe — AWS, Frankfurt | eu-central-1.aws | https://api.eu-central-1.aws.commercetools.com |
| North America — Google Cloud, Iowa | us-central1.gcp | https://api.us-central1.gcp.commercetools.com |
| North America — AWS, Ohio | us-east-2.aws | https://api.us-east-2.aws.commercetools.com |
| Australia — Google Cloud, Sydney | australia-southeast1.gcp | https://api.australia-southeast1.gcp.commercetools.com |
The auth host is the same segment with auth. in front of it. You do not have to memorise any of this — read the host segment straight out of the API URL in your credentials block, between api. and .commercetools.com. That middle part is what Pimcore asks for.
Now Plug It Into Pimcore
With the credentials block in hand, the Pimcore side is a two-minute job. In Pimcore Studio, open Commercetools → Credentials → Add Credential:
- Project Key — straight from the block, e.g.
acme-eu. - Client ID — straight from the block.
- Client Secret — the one-time secret.
- Region — the host segment only, e.g.
europe-west1.gcp. Not the full URL. The connector builds both the API host and the auth host from it, which is why there is no separate API URL or Auth URL field to fill in. - Scopes — optional, one per line or space-separated, project key suffix included (
view_products:acme-eu). Leave it blank and the connector requests a token without narrowing the scope, so you get everything the API client was created with. Filling it in narrows the token further — useful when one client is deliberately broader than this integration should be. - Active — tick it. Only one credential can be active at a time, and jobs always run against the active one.
Then click Save. the connector fetches a token and reads the project back before it stores anything. On success you get “Saved and connection verified” and the row’s Status turns green. On failure nothing is persisted at all — a broken credential can never end up in your database waiting to fail at 2 a.m. during a scheduled job.
You can store several projects here — staging and production, or one per region — and each keeps its own private set of local-to-remote id links, so switching between them never mixes their catalogs.
Try the Pimcore commercetools Connector
Credentials in place, the rest is mapping and jobs: bind commercetools categories, product types and products to your own Pimcore classes, then run imports and exports from inside Pimcore Studio with live progress, a Stop control and safe re-runs. Get the Pimcore commercetools Connector from the Webkul Store, or talk to our team for a live demo and help fitting it to your catalog.