{"id":552734,"date":"2026-08-11T09:36:29","date_gmt":"2026-08-11T09:36:29","guid":{"rendered":"https:\/\/webkul.com\/blog\/?p=552734"},"modified":"2026-08-11T09:36:29","modified_gmt":"2026-08-11T09:36:29","slug":"generate-commercetools-credential-for-pimcore","status":"publish","type":"post","link":"https:\/\/webkul.com\/blog\/generate-commercetools-credential-for-pimcore\/","title":{"rendered":"How to Generate commercetools API Credentials for Pimcore"},"content":{"rendered":"\n

Before Pimcore 12<\/strong> can read a single product out of your commercetools<\/strong> project \u2014 or push one back \u2014 it needs an API client<\/strong>. Everything else in a catalog sync is configuration. The credentials are the part that decides whether the connection works at all.<\/p>\n\n\n\n

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 \u2014 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<\/a>.<\/p>\n\n\n\n

First: commercetools Has No \u201cAPI Key\u201d<\/h2>\n\n\n\n

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.<\/p>\n\n\n\n

commercetools uses the standard OAuth2 client credentials flow<\/a>. You create an API client<\/strong>, which gives you a Client ID<\/strong> and a Client Secret<\/strong>. Those are not the token \u2014 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<\/strong> by default, and whatever is calling the API is expected to fetch a new one when it does.<\/p>\n\n\n\n

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<\/em> and never think about tokens again \u2014 no expiry to babysit, no credential to re-paste every two days.<\/p>\n\n\n\n

Step 1 \u2014 Create the API Client in the Merchant Center<\/h2>\n\n\n\n

The full official walkthrough is Create an API client<\/a> in the commercetools docs. Condensed:<\/p>\n\n\n\n

    \n
  1. Log in to the commercetools Merchant Center<\/strong> for the region your project lives in.<\/li>\n\n\n\n
  2. Select the project you want Pimcore to sync with. Credentials are per project<\/strong>, not per account.<\/li>\n\n\n\n
  3. Go to Settings \u2192 Developer settings<\/strong>.<\/li>\n\n\n\n
  4. Open the API clients<\/strong> tab and click Create new API client<\/strong>.<\/li>\n\n\n\n
  5. Give it a name you will recognise in six months \u2014 Pimcore Catalog Sync<\/em> beats test client 3<\/em>. The name appears in the API client list and is how you decide later which one is safe to revoke.<\/li>\n\n\n\n
  6. Choose the scopes. This is the part worth slowing down for \u2014 see the next section.<\/li>\n\n\n\n
  7. Click Create API client<\/strong>.<\/li>\n<\/ol>\n\n\n\n
    \"image-34\"<\/figure>\n\n\n\n
    \"image-36\"<\/figure>\n\n\n\n

    Step 2 \u2014 Which Scopes Does a Pimcore Catalog Sync Need?<\/h2>\n\n\n\n

    The Merchant Center offers scope templates, and the tempting one is Admin client<\/strong> \u2014 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\u2019 own getting-started guide<\/a> recommends keeping scopes to the minimum necessary.<\/p>\n\n\n\n

    Here is what a Pimcore sync actually needs:<\/p>\n\n\n\n

    What you want to sync<\/th>Scope<\/th>Needed for<\/th><\/tr><\/thead>
    Products and variants<\/td>view_products<\/code><\/td>Import into Pimcore<\/td><\/tr>
    Product types (families) and their attribute definitions<\/td>view_product_types<\/code><\/td>Import<\/td><\/tr>
    The category tree<\/td>view_categories<\/code><\/td>Import<\/td><\/tr>
    Products and variants, written back<\/td>manage_products<\/code><\/td>Export from Pimcore<\/td><\/tr>
    Product types, written back<\/td>manage_product_types<\/code><\/td>Export<\/td><\/tr>
    Categories, written back<\/td>manage_categories<\/code><\/td>Export<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n

    Two useful shortcuts.<\/strong> If you only ever pull commercetools into Pimcore, grant the three view_<\/code> scopes and stop \u2014 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_<\/code> scopes cover their view_<\/code> equivalents, so you do not need both.<\/p>\n\n\n\n

    Scopes carry the project key.<\/strong> A scope is not view_products<\/code>; it is view_products:{projectKey}<\/code>. So for a project keyed acme-eu<\/code> the real scope string is:<\/p>\n\n\n\n

    view_products:acme-eu view_product_types:acme-eu view_categories:acme-eu<\/pre>\n\n\n\n
    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 \u2014 a scope without the project key suffix is rejected.<\/p>\n\n\n\n
    Full reference, if your setup needs something outside a catalog sync: commercetools OAuth scopes<\/a>.<\/p>\n\n\n\n
    \"image-37\"<\/figure>\n\n\n\n
    Step 3 \u2014 Save the Credentials. You Get One Chance<\/h2>\n\n\n\n
    The moment you click\u00a0Create API client<\/strong>, commercetools shows you a block of values.\u00a0This block is displayed exactly once.<\/strong>\u00a0Navigate away and the client secret is gone permanently \u2014 there is no reveal-again, no recovery, and your only option is to delete the client and create another.<\/p>\n\n\n\n
    Download the Environment Variables (.env)<\/strong> file the page offers, or copy the values into your password manager, before<\/em> you do anything else. The file arrives named {projectKey}_{API client name}.env<\/code>.<\/p>\n\n\n\n
    Six values come out, and this is what each of them is:<\/p>\n\n\n\n
    Value<\/th>What it is<\/th><\/tr><\/thead>
    Project key<\/strong><\/td>The identifier of the commercetools project itself, e.g. acme-eu<\/code>. It is part of every API URL and part of every scope string. Not a secret.<\/td><\/tr>
    Client ID<\/strong><\/td>The username half of the credential. Not a secret, though there is no reason to publish it.<\/td><\/tr>
    Secret<\/strong><\/td>The password half. This is the one shown once. Treat it as a production password.<\/td><\/tr>
    Scope<\/strong><\/td>The exact space-separated scope string granted to this client, project key suffixes included. Useful to keep \u2014 it is the definitive record of what this client can do.<\/td><\/tr>
    API URL<\/strong><\/td>Where data requests go, e.g. https:\/\/api.europe-west1.gcp.commercetools.com<\/code>. Region-specific.<\/td><\/tr>
    Auth URL<\/strong><\/td>Where the token exchange happens, e.g. https:\/\/auth.europe-west1.gcp.commercetools.com<\/code>. Region-specific, and a different host from the API URL.<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
    If you want to see the exchange for yourself before involving Pimcore, this is the whole of it:<\/p>\n\n\n\n
    curl https:\/\/auth.europe-west1.gcp.commercetools.com\/oauth\/token -X POST \\\n  --basic --user "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET" \\\n  -d "grant_type=client_credentials&scope=view_products:acme-eu"<\/pre>\n\n\n\n
    A working credential returns a bearer token with \"expires_in\": 172800<\/code> \u2014 48 hours. A broken one returns 401<\/code>, and the next section is about why that usually is not the password.<\/p>\n\n\n\n
    \"image-38\"<\/figure>\n\n\n\n
    The Region Trap<\/h2>\n\n\n\n
    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.<\/p>\n\n\n\n
    commercetools runs fully isolated regions<\/a>. A project in Belgium does not exist in Iowa. Accounts do not cross regions either \u2014 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<\/strong>, 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.<\/p>\n\n\n\n
    If a fresh credential returns 401, check the region before you touch the secret.<\/strong><\/p>\n\n\n\n
    The regions and the host segment each one uses:<\/p>\n\n\n\n
    Region<\/th>Host segment<\/th>API URL<\/th><\/tr><\/thead>
    Europe \u2014 Google Cloud, Belgium<\/td>europe-west1.gcp<\/code><\/td>https:\/\/api.europe-west1.gcp.commercetools.com<\/code><\/td><\/tr>
    Europe \u2014 AWS, Frankfurt<\/td>eu-central-1.aws<\/code><\/td>https:\/\/api.eu-central-1.aws.commercetools.com<\/code><\/td><\/tr>
    North America \u2014 Google Cloud, Iowa<\/td>us-central1.gcp<\/code><\/td>https:\/\/api.us-central1.gcp.commercetools.com<\/code><\/td><\/tr>
    North America \u2014 AWS, Ohio<\/td>us-east-2.aws<\/code><\/td>https:\/\/api.us-east-2.aws.commercetools.com<\/code><\/td><\/tr>
    Australia \u2014 Google Cloud, Sydney<\/td>australia-southeast1.gcp<\/code><\/td>https:\/\/api.australia-southeast1.gcp.commercetools.com<\/code><\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
    The auth host is the same segment with auth.<\/code> in front of it. You do not have to memorise any of this \u2014 read the host segment straight out of the API URL in your credentials block, between api.<\/code> and .commercetools.com<\/code>. That middle part is what Pimcore asks for.<\/p>\n\n\n\n
    Now Plug It Into Pimcore<\/h2>\n\n\n\n
    With the credentials block in hand, the Pimcore side is a two-minute job. In Pimcore Studio<\/a>, open Commercetools \u2192 Credentials \u2192 Add Credential<\/strong>:<\/p>\n\n\n\n