How to Connect Pimcore 12 to Shopify

Running your catalog in Pimcore 12 and selling on Shopify means the same collections, products, variants, images and translations have to exist in two places at once. Re-keying that by hand does not scale — and every manual step is another chance for the two catalogs to drift apart.

The Pimcore Shopify Connector closes that gap. It syncs your catalog both directions between Pimcore 12 and a Shopify store over the Shopify Admin GraphQL API — no CSV files, no middleware. This guide walks you through the whole flow: connect a store, map your data, then run every import and export job from inside Pimcore.

Pimcore Shopify Connector: Key Features

• Two-way sync — import Shopify → Pimcore and export Pimcore → Shopify, entity by entity.
• Full catalog coverage — collections, products, variants, product options, metafield definitions, metafield values, images, inventory and prices.
• Native Pimcore variants — a Shopify product with variants becomes one parent object plus real Pimcore variant children, kept as a true mirror.
• Metafields become a real data structure — Shopify metafield definitions are turned into a typed, localized Pimcore Classification Store you can actually edit.
• Images are pushed, not linked — assets are uploaded to Shopify as bytes via staged upload, so private Pimcore assets still land in your store.
• Shopify Translation API — localized titles, descriptions, SEO fields, option names/values and metafield values sync per language.
• Channels and currencies — per-channel, per-currency pricing on the Pimcore side, chosen at export time.
• Map to your own classes — bind each entity to any Pimcore DataObject class and map every field yourself.
• Live job monitoring — every sync runs in the background with progress, counters, a Stop control and an activity log.
• Never duplicates — a local↔Shopify id map decides create-vs-update, so re-running a job is always safe.

Before You Start

You will need:

• A running Pimcore 12 instance with Studio, and the Pimcore Shopify Connector installed.
• A Shopify store with a custom app created in the Shopify admin, giving you an Admin API access token (shpat_...) with read/write scopes for products, inventory, translations, locations and publications.
• A background worker running. Every job is queued through Symfony Messenger — without a consumer, jobs stay pending forever. The connector ships a supervisord config for it.
• Your languages configured in Pimcore (Settings → System Settings → Localization & Internationalization) before you connect the store — you will map Shopify locales onto them.

Once installed, a Shopify Connector section appears in the Studio left nav with Credentials, Mappings, Import Job, Export Job and Metafield Definitions.

Step 1 — Connect Your Shopify Store

1. Open Shopify Connector → Credentials.
2. Click Add Credential.
3. Fill in the form:
   • Shop Domain — e.g. your-store.myshopify.com
   • Access Token — your shpat_... Admin API token
   • API Version — pick from the list (newest first)
4. Click Validate. This calls Shopify and confirms the token works — you will see “Connected to <your shop name>”. If a scope is missing, a “Some scopes are missing” warning tells you which. Save stays disabled until Validate succeeds, so a broken credential can never be stored.
5. Now the sync settings appear — “Select locales and channels to sync”:
   • Locales — which Shopify locales to sync (the primary one is marked (primary))
   • Channels — which Shopify sales channels (publications) products get published to
   • Locations — which locations inventory is written to
   • Locale mapping (Shopify locale to Pimcore language) — map each Shopify locale onto a Pimcore language. The primary locale must be mapped or the form refuses to save.
6. Tick Active (only one credential may be active).
7. Click Save. You get “Saved successfully”.

The access token is write-only over the API — it is never sent back to the browser, and the list only shows whether a token is Set or Missing. When editing a credential later, leave the token blank to keep the current one.

Good to know: you can store several stores here, but only one is Active at a time — saving one as active automatically deactivates the others, and every job runs against the Active store. Each store keeps its own private id map, so switching between stores never mixes catalogs.

Step 2 — Map Shopify Entities to Your Pimcore Classes

The connector ships default DataObject classes — WkProduct (variant-enabled), WkCategory, WkAttribute, WkAttributeOption, WkFamily, WkChannel — but it holds no hard reference to any of them. They are defaults, not requirements: the Mappings screen is where you point the connector at your data model. Mapping has two parts.

2a. Bind a Pimcore class to each entity

1. Open Shopify Connector → Mappings.
2. On the Object Mapping tab: “Choose the Pimcore class for each Shopify entity, and the field used as the unique code (match key).”
3. For each entity — Category and Product — pick the Pimcore class and the Match key (code) field. The match key is what records are matched on (typically the Shopify handle), so it is what keeps re-runs from duplicating.
4. Click Save object mapping.

2b. Map the fields

1. Switch to the Category or Product tab. (Until you have saved an object mapping, the tab just tells you: “Select and save a Pimcore class for this entity in the Object Mapping tab first.”)
2. Each row is a Shopify field on the left and a Pimcore field dropdown on the right. Unmapped rows read “Not mapped”.
3. On the Product tab there is also a Default value column — a fixed value used when the field isn’t mapped.
4. Below that, map your images under Media mappings.
5. Click Save field mapping. Repeat for the other entity.

Field mapping is validated before any export runs, so a broken map fails loudly and early instead of writing half a catalog.

Step 3 — Importing from Shopify

All imports live on one screen: Shopify Connector → Import Job. You pick a Job type, click the run button, and the job starts in the background — no confirmation dialog, no store picker (it always uses the Active credential).

Import is read-only on Shopify and safe to repeat: re-running reuses existing objects via the id map, so it never duplicates.

Run the four jobs in this order, because products depend on the other three.

3a. Import Categories (Shopify Collections)

1. Open Import Job, set Job type to Categories.
2. Click Import Categories.

3b. Import Attributes (Product Options)

1. Set Job type to Attributes.
2. Click Import Attributes.

Shopify has no standalone “attributes” entity, so the connector derives them by scanning your products: every product option name (Size, Colour) becomes a WkAttribute, and every option value (Small, Red) becomes a WkAttributeOption. Synthetic options such as Title / Default Title on simple products are skipped.

3c. Import Metafields (Definitions)

1. Set Job type to Metafields.
2. Click Import Metafields.

This imports Shopify’s metafield definitions — for both product and variant owners — and turns them into a real, typed, localized Pimcore Classification Store. Your Shopify custom data stops being a black box and becomes editable structure in Pimcore.

3d. Import Products

1. Set Job type to Products.
2. Pick a Channel and a Currency — this is the pricing slot Shopify’s price and cost get written into.
3. Click Import Products.

Each product pulls in its core and localized fields, images (downloaded into Pimcore Assets, de-duplicated), metafield values, inventory (quantity, tracked flag, unit cost, weight), price/cost into the chosen channel+currency, and its collections.

Variants become real Pimcore variants — one parent object plus a native variant child per Shopify variant. It is a true mirror: variants deleted on Shopify are pruned in Pimcore, and clearing a product’s media on Shopify clears it in Pimcore too.

After the run, imported objects are re-indexed so they show up immediately in Studio search.

Step 4 — Managing Metafield Definitions

Shopify Connector → Metafield Definitions lists everything Import Job → Metafields brought in, with Owner, Namespace.Key, Name, Shopify Type, Pimcore Type, List? and Pinned.

• Edit a definition to change its Name / Description, or flip Pin to product editor — pinned definitions show by default on the product page, unpinned ones hide under “Show all”. Shopify’s own fields stay read-only.
• Add Metafield Definition to create a brand-new one in Pimcore (Owner, Namespace, Key, Name, Shopify Type, Description). It exists in Pimcore straight away; push it to Shopify with Export Job → Metafield Definitions.
• Delete removes the definition and its product field in Pimcore only — Shopify is never touched. If the field already holds values, you get a second confirmation before anything is destroyed.

Step 5 — Exporting to Shopify (Push Pimcore Out)

All exports live on Shopify Connector → Export Job. Same pattern: pick a Job type, click the run button. The field mapping is validated first, so a bad map stops the job before it writes anything.

5a. Export Collections

1. Open Export Job, set Job type to Collections.
2. Click Export Collections.

Categories are created or updated on Shopify, translations included.

5b. Export Metafield Definitions

1. Set Job type to Metafield Definitions.
2. Click Export Metafield Definitions.

Definitions you created in Pimcore are pushed to Shopify. If a definition already exists there, the connector adopts it and updates instead of erroring out.

5c. Export Products

1. Set Job type to Products.
2. Pick a Channel and a Currency — both are required; the run button stays disabled with the tooltip “Select a channel and currency first” until you do. This is the price the export sends.
3. Optionally narrow the run: the filter box reads “Filter by product handle or SKU — comma or newline separated. Leave empty to export all products.”
4. Click Export Products.

Each product is written to Shopify as one declarative operation carrying its fields, options, variants, metafields, images and collections at once. Because it is declarative, removing a category in Pimcore removes the product from that collection on Shopify.

• Images are uploaded, not linked. Shopify cannot fetch a private Pimcore URL, so the connector reads the asset bytes and pushes them through a staged upload.
• Inventory is written to your selected location for variants that track stock.
• Publishing — the product is published to the sales channels you selected on the credential.
• Translations are registered for every mapped non-primary locale — titles, descriptions, SEO fields, option names and values, metafield values.

It never duplicates. The connector first looks up the local↔Shopify id map; if there is no link it adopts the existing product by handle, or creates it. And if a product was deleted on Shopify behind your back, the connector detects it, drops the stale mapping and re-creates the product in the same pass instead of failing.

Watching, Stopping & Re-running Any Job

Every import and export runs in the background and is tracked. Both screens show a history table with ID, Type, Start Date/Time, User, Status, Read, Created, Updated, Failed and Action. Status reads Started, In Progress, Completed, Failed or Stopped.

• Open a run — click the eye icon in Action. The detail view shows a progress bar, the Read / Created / Updated / Failed counters, a Summary card (status, total, start and end time, timing, estimated time remaining) and an Activity log.
• Stop a run — while it is running, click Stop. The confirmation is explicit: “The current item finishes first; objects and mappings already written are kept.” You then see “Stop requested. The job exits after the current item.”
• Re-run safely — just run the job again. Create-vs-update is decided from the id map, so a second run updates instead of duplicating.

One bad row never kills a run. If a product fails, it is counted under Failed, a plain-English reason is written to the job log, and the job carries on with the rest. Genuine blockers — an unmapped class, an invalid field mapping, or a missing Shopify scope — fail the job up front instead of “successfully importing 0 records”.

Languages, Channels & Permissions

Multi-language runs on Shopify’s Translation API. You map Shopify locales to Pimcore languages once, on the credential. Import writes the base value into your primary language and pulls each mapped locale’s translation into its own language; export reads the primary language as the Shopify base and registers the rest.

Channels and currencies are a Pimcore-side pricing model: a WkChannel carries a list of ISO-4217 currencies, and selecting a channel on a product activates exactly that channel’s price and cost fields. Import and export both run against a chosen channel + currency, so one catalog can feed different price sets.

Access is fine-grained. There is one master permission plus separate keys for credentials, mapping, metafields, 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.

Try the Pimcore Shopify Connector

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