How to Connect Pimcore 12 to commercetools (Step by Step)

Running your product catalog in Pimcore 12 and selling through commercetools means the same categories, product types, and products have to live in two systems at once. Doing that by hand — re-keying every attribute, re-uploading every image, rebuilding every category tree — does not scale, and every manual step is a chance for the two catalogs to drift apart.

The Pimcore commercetools Connector closes that gap. It syncs catalog data both directions between a commercetools project and Pimcore 12, straight over the commercetools HTTP API — no middleware, no CSV exports, no vendor SDK in the middle. This guide walks you through the whole flow: connect a project, map your data, then run each import and export job from inside Pimcore Studio.

Pimcore commercetools Connector: Key Features

• Two-way sync — import commercetools → Pimcore and export Pimcore → commercetools, entity by entity.
• Categories, product types (families), and products — full catalog coverage, including localized fields, prices, typed attributes, and images.
• Native Pimcore variants — a commercetools product with variants becomes one parent object plus real Pimcore variant children.
• Images handled end-to-end — downloaded into Pimcore Assets on import, uploaded as bytes and published on export.
• Map to your own classes — bind each entity to any Pimcore DataObject class and map every field yourself.
• OAuth2, encrypted credentials — client-credentials auth, connection verified on save, secret encrypted at rest.
• Live job monitoring — every sync runs in the background with per-step counters, a Stop control, and a per-job error log inside Studio.
• Idempotent and resilient — a bad row is logged and skipped, not fatal; re-running is always safe.
• Fine-grained permissions — a master key plus separate keys for credentials, mapping, import, and export.

Before You Start

You will need:

• A running Pimcore 12 instance with Studio, and the Pimcore commercetools Connector installed.
• A commercetools project and an API Client created in the commercetools Merchant Center (that gives you a project key, client ID, client secret, region, and scopes).

Once the connector is installed you will see a Commercetools section in the Studio left navigation, with Credentials, Mappings, an Import group, and an Export group.

Step 1 — Connect Your commercetools Project

The connector authenticates with the standard OAuth2 client-credentials grant.

1. In Studio, open Commercetools → Credentials.
2. Click Add Credential. A dialog opens.
3. Fill in the fields:
   • Project Key — your commercetools project key.
   • Client ID and Client Secret — from your commercetools API Client.
   • Region — e.g. europe-west1.gcp. The connector builds the correct API and auth hosts for that region automatically.
   • Scopes — optional, one per line or space-separated (e.g. view_products:my-project).
   • Tick Active (only one credential may be active).
4. Click Save.

On save the connector verifies the connection before it stores anything — If the credentials are valid you get “Saved and connection verified” and the row’s Status turns green; if not, the save is rejected with an error and nothing is persisted. The client secret is encrypted at rest and never shown again — when you edit a credential later, leave the secret blank to keep the current one.

Good to know: you can store several commercetools projects here, but only one is Active at a time, and jobs always run against the Active credential. Each project keeps its own private set of local-to-remote id links, so switching between projects never mixes their catalogs.

Step 2 — Map commercetools Entities to Your Pimcore Classes

The connector does not force a fixed schema on you. It ships default DataObject classes — WkCategory, WkFamily, WkAttribute, and a variant-enabled WkProduct — but the Mappings screen is where you make the connector fit your data model. Mapping has two parts.

2a. Bind a Pimcore class to each entity

1. Open Commercetools → Mappings.
2. On the Object Mapping tab you will see a row per entity — Category, Family, Product — each with a Pimcore class dropdown.
3. Pick the class each entity should read into (keep the defaults, or point them at your own classes).
4. Click Save object mapping.

2b. Map the fields

1. Still in Mappings, switch to the entity’s own tab (Category, Family, or Product).
2. Each row is a commercetools field on the left and a Pimcore field dropdown on the right. Required fields are marked with a red asterisk (for products: sku, key, name).
3. Choose the target field for each — both plain and localized class fields are offered (localized ones are labelled accordingly). Each Pimcore field can be used once.
4. Click Save field mapping.
5. Repeat for the other entities.

Product custom attributes need no per-attribute setup — they are matched by code against your class fields at sync time, using the attribute definitions carried on the product’s family. Mapping is global: one shared map serves every stored project, so you configure it once.

Step 3 — Importing from commercetools

Import runs one entity at a time, and order matters because products link to categories and families. Run the jobs in this sequence:

3a. Import Categories

1. Open Commercetools → Import → Categories.
2. Click Run Import. You will see a “Import started” toast and the job’s detail tab opens automatically.

Categories come in as a tree, not a flat list — the connector reads them parents first, so every parent exists before its children link to it, rebuilding the full hierarchy with localized name, slug, description, and meta fields.

3b. Import Families (commercetools Product Types)

1. Open Commercetools → Import → Families.
2. Click Run Import.

A commercetools product type is imported as a family: its attribute definitions become WkAttribute objects linked to the family, so the structure that governs your products travels with them.

3c. Import Products

1. Open Commercetools → Import → Products.
2. Click Run Import.

Each product pulls in its core and localized fields, price (converted from commercetools’ cent-based money to a plain value), typed attribute values, family and category links, and images downloaded to Pimcore Assets. Variants become real Pimcore variants — one parent WkProduct plus a native variant child per additional variant, with per-variant attribute values kept in a field collection. After the run, imported objects are re-indexed so they appear immediately in Studio search.

Note: import screens run against the Active credential — you don’t pick a project on the run form.

Step 4 — Exporting to commercetools

Export mirrors import and enforces the right order so nothing lands half-built. Run families before products, because a product’s type is mandatory in commercetools.

4a. Export Categories

1. Open Commercetools → Export → Categories.
2. Click Run Export.

Categories export parents-first and re-create the nesting in commercetools.

4b. Export Families

1. Open Commercetools → Export → Families.
2. Click Run Export.

Pimcore attribute types are translated into the matching commercetools attribute types. Export is deliberately conservative: existing attribute definitions on a remote product type are never modified or removed — only genuinely new ones are added — so a sync can’t break a product type other products depend on.

4c. Export Products (optionally filtered by SKU)

1. Open Commercetools → Export → Products.
2. To push everything, just click Run Export.
3. To push only specific products, click Filter, and in the SKUs box enter the SKUs (one per line or comma-separated — leave it empty to export all), then click Apply.
4. Click Run Export.

Products export with their variants, localized values, category references, and attributes, then publish. Prices are sent on create and left untouched on later updates, so an export never overwrites pricing you manage in commercetools. Images are handled as a final step: uploaded to commercetools as bytes, staged, and published; the remote gallery is kept as a mirror of the Pimcore gallery (new images added, stale ones removed).

Watching, Stopping & Re-running Any Job

Every import and export runs in the background and is tracked as a job you can watch live. Each run screen shows a history table with columns Job ID, Started At, Username, Credential, Status, Warnings, and Action. Status tags read Started, In Progress, Completed, Failed, or Stopped.

• Open a run — click View in the Action column. The job detail shows Job Information, a Progress bar, per-step counters (Read, Created, Updated, Skipped, Failed), and a Warnings & Errors / Activity log.
• Stop a run — while a job is running, open it and click Stop in the Job Information card. It stops cleanly: “The current item finishes first; objects and mappings already written are kept.”
• Re-run safely — just run the job again. The connector keeps a local ↔ remote id map per project and entity and decides create-vs-update from it, so a second run updates instead of duplicating.

When commercetools rejects a row, the connector surfaces its error message — not a bare “HTTP 400” — so you know exactly which product and field to fix. A single bad row is counted and skipped; the rest of the batch keeps going.

Localization & Permissions

Multi-language is automatic. The connector matches Pimcore languages to your commercetools project locales (for example en ↔ en-US), fanning localized values out per language on import and collapsing them back on export. You manage languages in Pimcore as usual.

Access is fine-grained. There is one master permission plus separate keys for credentials, mapping, import, and export. Grant the master key for full access, or hand out only the areas a role needs — the rule is enforced server-side, not just hidden in the UI.

For Developers: Run It From the Command Line

Everything the UI does is also on the CLI, which makes the connector easy to schedule or script:

• commercetools:import and commercetools:export — run a sync for a chosen project (export also takes a repeatable --sku filter).
• commercetools:credentials — list, create, edit, and delete projects.
• commercetools:objects:install — build the default DataObject classes and seed the default mappings, idempotently.

Try the Pimcore commercetools Connector

Ready to connect Pimcore 12 and commercetools? Get the Pimcore commercetools Connector from the Webkul Store, or reach out to our team for a live demo and help fitting it to your catalog.