Integrate product data

Product data is the foundation of a commercetools catalog. Whether your products originate in a Product Information Management (PIM) system, an enterprise resource planning (ERP) system, or a combination of both, a well-planned integration keeps your catalog accurate, searchable, and current without letting one slow feed block another.

This guide covers the decisions that shape a product data integration: which system owns each attribute, whether to configure a Connector or build the flows yourself, how to map an external product model onto the commercetools catalog, and how to load the catalog in bulk and keep it synchronized. It treats product content, Prices, and Inventory as separate synchronization concerns, because they change at different rates and fail independently.

Plan your product data integration

Assign a source of truth per attribute

Designate one system as the authoritative writer for each attribute, and make the commercetools copy read-only for it. A PIM typically owns enriched content such as names, descriptions, images, and specifications; an ERP typically owns SKUs, list Prices, and stock. Treat each row as a one-way contract, and reject or reconcile changes that originate on the read-only side.

Confirm the Inventory and contract-Price rows against the linked guides before you rely on the defaults, because those flows are owned by the systems that own Orders and financial data.

Answer the questions that change the design

Record the following before choosing an approach, because each answer moves the architecture:

• How many sources feed the catalog? A single PIM with a clear source of truth is the simplest case. Multiple systems, such as a PIM for content, a DAM for media, and an ERP for Prices and stock, add sequencing and conflict rules.
• Is the flow one-way or bi-directional? One-way, from the external system to commercetools, is the recommended default. Bi-directional synchronization, where some attributes edited in commercetools flow back, is more expensive: you must define which attributes sync back and how conflicts resolve. Do not assume bi-directional.
• Is product data editable in the Merchant Center? If product managers edit attributes in commercetools, decide which attributes remain owned by the external system, and restrict who can edit them.
• What volume, and how often does each domain change? Core product data changes infrequently, Prices change on a schedule, and stock changes constantly. These are different integrations with different cadences, even when they leave the same system.
• Which locales, currencies, and Channels are in scope? This determines the localization, Price, and Inventory mapping, and whether one extract serves every Store.
• What must not be synchronized? Not every PIM attribute belongs in commercetools. Map only what search, display, pricing, and fulfillment need, and leave the rest in the source system.

Record special requirements

Capture constraints that could require custom extraction, transformation, or hosting, because each one can move the decision in the next section from configuring a Connector toward forking or building one:

• Reference or related entities, such as cross-sells and related products, that the PIM models as first-class links.
• Attribute values scoped by a PIM channel or context, where one attribute holds different values per scope.
• Store- or market-specific catalogs that need Product Selections or Product Tailoring.
• Measurement-unit conversion, quirks in variant and family modeling, or publish and staging rules.
• Data residency, retention, or audit constraints that restrict where the integration runs.

Multiple sources of product data

When several systems write to the same Product, define the ownership boundary explicitly so no source overwrites another:

1. The source of truth for each attribute. Determine which attributes come from each system, for example descriptions from the PIM and stock from the ERP. To keep externally owned attributes from being changed by hand in the Merchant Center, group them in a restricted AttributeGroup and grant editing permission only to the responsible teams. This is a Merchant Center permission boundary, not an API-level lock: it does not restrict an API Client, so keep the Product write scopes of each integration narrow as well.
2. The process for creating Products. Send the initial version of a Product to commercetools once, when it is first created. Restrict subsequent updates from each source to only the attributes that source owns, and never perform a blind full overwrite that replaces another system's fields.
3. The number of integrations required. Choose between a single integration that consolidates all sources, or a primary process that creates the Product and secondary processes that add data afterward.
4. The write-back path, for bi-directional flows only. Identify the attributes for which commercetools is the source of truth, and ensure only those attributes sync back to the source system. Filter your own writes so an inbound update does not loop back out.

Choose a connector

Start with the option that requires your team to build and maintain the least custom integration logic. A deployable Connector that already syncs your PIM is almost always the right choice; build a custom integration only when no Connector fits a recorded requirement.

Check for an existing product data Connector

GET https://connect.{region}.commercetools.com/connectors/search?integrationTypes=pim&integrationTypes=erp

Evaluate each candidate against the attributes, directions, mappings, Regions, locales, and peak volume you recorded, rather than against its headline. Record the Connector key and version you evaluated.

Prove that a gap is not configuration

Fork or build

If a Connector matches your PIM and has a genuine gap that configuration cannot close, and its source is available, fork it. Add only the difference, such as a missing resource type or a bi-directional write-back, and deploy the result as an Organization Connector. You keep the working sync engine, keying, and dependency handling.

commercetools connect init my-pim-connector
commercetools connect application add

Choose your integration approach

The approach depends on the frequency of updates, the volume of data, and the capabilities of your source. Most catalogs need more than one approach: a bulk load for the initial catalog and periodic refreshes, and an incremental flow for time-critical changes.

Full versus incremental uploads

Full uploads send the entire catalog to commercetools. They take longer and leave the catalog partially updated during the run, so use them for the initial load and periodic complete refreshes.

A robust integration does both: an incremental flow for freshness, and a scheduled full reconciliation that catches missed events and repairs drift.

Event-driven versus bulk, and the application shape

Match the delivery mechanism to the cadence, then pick the runtime shape it implies:

• Event-driven flows handle changes as they occur and give near real-time updates. The source pushes each change to an authenticated endpoint, which maps to a service webhook application. Choose this when real-time accuracy matters.
• Bulk flows run at scheduled intervals and are more efficient for large volumes where immediate updates are not essential. A schedule maps to a job application. Choose this for catalog refreshes and periodic synchronization.

Data mapping

Map only commerce-relevant data

Not every PIM attribute belongs in commercetools. Transfer only what search, display, pricing, or fulfillment needs, and leave the rest in the PIM, where it remains the source of truth. Every attribute you sync is one more thing to keep consistent.

Do not map Product Types one-to-one with PIM families

Type search-critical attributes precisely, and consolidate the rest

Split PIM attributes into two buckets:

• Search, filter, and display-critical attributes, such as brand, color, size, and material, map to their own typed Product Type attributes. Type each one precisely: enum or lenum for controlled vocabularies so faceting works, number with a unit for measurements, and boolean for flags. Key each enum option on the PIM's stable option code, not its localized label, because labels change per translation and would silently break faceting.
• Supplementary attributes that are displayed but never filtered consolidate into a single JSON text attribute rather than exploding into dozens of rarely used fields. This keeps the Product Type lean and the catalog queryable.

Map locales explicitly

Resolve categories and references by key

Reference or related entities, such as cross-sells, are often the gap a public Connector does not cover, so confirm the Connector maps them or treat it as a reason to fork.

Give every resource a stable key

Keep media, Prices, and Inventory on their own paths

Manage price and inventory separately

Price and Inventory change far more often and are more time-critical than descriptions and images. Implement them as separate, event-based integrations, even when they originate in the same system as product content, so a slow nightly catalog run never blocks a Price or stock update.

Solution A: bulk import with the Import API

Five Import API behaviors shape monitoring, retry, and ownership boundaries:

• Queued processing. An Import Response confirms acceptance for asynchronous processing as ImportOperation resources, not completion.
• Asynchronous reference resolution. A resolved reference can still fail commerce API validation. Follow the reference resolution behavior when designing retry and monitoring.
• Updates remove omitted fields. When you import an update to an existing Product or Product Variant, the import removes the values of any fields you omit. Include every value you want to keep, and restrict each source to the fields it owns. See Choose the right Product import endpoint.
• Bounded batch sizing. One import request carries at most 20 resources, so split every extract into batches of that size and send them in parallel. Size batches and containers according to the Import API best practices.
• Publication is explicit. An import does not publish a Product for you, and importing an update to a published Product behaves differently from creating one. Decide whether the sync publishes, and follow Manage published state of Products.

Import inventory data from the ERP

Inventory data often originates in an ERP system. A common pattern is to export the ERP data as a CSV file, parse it, and submit it to the Import API.

Consider the following example CSV from the ERP:

sku,quantityOnStock,restockableInDays,expectedDelivery
product-sku-1,100,5,2026-05-01T10:00:00.000Z
product-sku-2,250,3,2026-04-15T10:00:00.000Z
product-sku-3,0,10,2026-06-01T10:00:00.000Z

import { parse } from "csv-parse/sync";
import * as fs from "fs";

// Must not exceed the Import API limit on resources per request
const BATCH_SIZE = 20;

function batch<T>(items: T[], size: number): T[][] {
  const batches: T[][] = [];
  for (let i = 0; i < items.length; i += size) {
    batches.push(items.slice(i, i + size));
  }
  return batches;
}

// Parse the ERP CSV export
const csvContent = fs.readFileSync("erp-inventory-export.csv", "utf-8");
const records = parse(csvContent, { columns: true, skip_empty_lines: true });

// Map CSV rows to Import API InventoryImport resources
const inventoryImports = records.map((row) => ({
  key: `inventory-${row.sku}`,
  sku: row.sku,
  quantityOnStock: parseInt(row.quantityOnStock, 10),
  restockableInDays: parseInt(row.restockableInDays, 10),
  expectedDelivery: row.expectedDelivery,
}));

// Submit the inventory import operations, one batch per request
for (const resources of batch(inventoryImports, BATCH_SIZE)) {
  await apiRoot
    .inventories()
    .importContainers()
    .withImportContainerKeyValue({ importContainerKey: "pim-product-import" })
    .post({
      body: {
        type: "inventory",
        resources,
      },
    })
    .execute();
}

Import product data from the PIM

Product data typically comes from a PIM system, also often as a CSV export. Products contain KeyReference fields for resources such as Product Types and Categories. The Import API resolves these references automatically.

Consider the following example CSV from the PIM:

key,name.en,slug.en,description.en,productType,categories,sku,priceKey,price
blue-widget,"Blue Widget","blue-widget","A high-quality blue widget.","standard-product","widgets;accessories","blue-widget-sku","blue-widget-price","EUR 1999"
red-gadget,"Red Gadget","red-gadget","A versatile red gadget.","standard-product","gadgets","red-gadget-sku","red-gadget-price","EUR 2499"

Parse the CSV and submit the product data as import operations:

import { parse } from "csv-parse/sync";
import * as fs from "fs";

// Must not exceed the Import API limit on resources per request
const BATCH_SIZE = 20;

function batch<T>(items: T[], size: number): T[][] {
  const batches: T[][] = [];
  for (let i = 0; i < items.length; i += size) {
    batches.push(items.slice(i, i + size));
  }
  return batches;
}

// Parse the PIM CSV export
const csvContent = fs.readFileSync("pim-product-export.csv", "utf-8");
const records = parse(csvContent, { columns: true, skip_empty_lines: true });

// Map CSV rows to Import API ProductDraftImport resources
const productDraftImports = records.map((row) => {
  const [currencyCode, centAmountStr] = row.price.split(" ");
  return {
    key: row.key,
    name: { en: row["name.en"] },
    slug: { en: row["slug.en"] },
    description: { en: row["description.en"] },
    productType: {
      key: row.productType,
      typeId: "product-type",
    },
    categories: row.categories.split(";").map((catKey) => ({
      key: catKey.trim(),
      typeId: "category",
    })),
    masterVariant: {
      key: row.sku,
      sku: row.sku,
      prices: [
        {
          key: row.priceKey,
          value: {
            type: "centPrecision",
            currencyCode: currencyCode,
            centAmount: parseInt(centAmountStr, 10),
          },
        },
      ],
    },
  };
});

// Submit the product import operations, one batch per request
for (const resources of batch(productDraftImports, BATCH_SIZE)) {
  await apiRoot
    .productDrafts()
    .importContainers()
    .withImportContainerKeyValue({ importContainerKey: "pim-product-import" })
    .post({
      body: {
        type: "product-draft",
        resources,
      },
    })
    .execute();
}

Solution B: incremental sync with the HTTP API

Upsert inventory entries

async function upsertInventoryEntry(
  apiRoot,
  inventoryKey: string,
  sku: string,
  quantityOnStock: number
) {
  try {
    // Attempt to fetch the existing inventory entry by key
    const existing = await apiRoot
      .inventories()
      .withKey({ key: inventoryKey })
      .get()
      .execute();

    // Resource exists: update it
    const updated = await apiRoot
      .inventories()
      .withKey({ key: inventoryKey })
      .post({
        body: {
          version: existing.body.version,
          actions: [
            {
              action: "changeQuantity",
              quantity: quantityOnStock,
            },
          ],
        },
      })
      .execute();

    return updated.body;
  } catch (error) {
    if (error.statusCode === 404) {
      // Resource doesn't exist: create it
      const created = await apiRoot
        .inventories()
        .post({
          body: {
            key: inventoryKey,
            sku: sku,
            quantityOnStock: quantityOnStock,
          },
        })
        .execute();

      return created.body;
    }
    throw error;
  }
}

Upsert products

The same pattern applies to Products. Fetch by key, then create or update depending on whether the Product already exists.

async function upsertProduct(
  apiRoot,
  productKey: string,
  productData: {
    name: { en: string };
    slug: { en: string };
    productType: { key: string; typeId: "product-type" };
    description?: { en: string };
  }
) {
  try {
    // Attempt to fetch the existing Product by key
    const existing = await apiRoot
      .products()
      .withKey({ key: productKey })
      .get()
      .execute();

    // Resource exists: update it
    const updated = await apiRoot
      .products()
      .withKey({ key: productKey })
      .post({
        body: {
          version: existing.body.version,
          actions: [
            {
              action: "changeName",
              name: productData.name,
            },
            {
              action: "changeSlug",
              slug: productData.slug,
            },
          ],
        },
      })
      .execute();

    return updated.body;
  } catch (error) {
    if (error.statusCode === 404) {
      // Resource doesn't exist: create it
      const created = await apiRoot
        .products()
        .post({
          body: {
            key: productKey,
            name: productData.name,
            slug: productData.slug,
            productType: productData.productType,
            description: productData.description,
          },
        })
        .execute();

      return created.body;
    }
    throw error;
  }
}

Build a resilient HTTP API client

Choose the right API

Verify the integration

Before the first production run, test the mapping in isolation. A mapping is a pure transformation from a source record to a commercetools draft, so you can test it with fixtures and no credentials. Cover the cases that silently corrupt a catalog: locale codes that differ between the systems, controlled vocabularies keyed on a stable code rather than a translated label, measurement units normalized to one measure, keys derived deterministically from a source identifier, references emitted by key, and out-of-scope attributes omitted rather than sent as empty values.

Count before you write. Ask the source how many records the run covers, print the count, and refuse a run above a threshold unless the operator confirms it explicitly. An unbounded first sync can pull a full PIM export of hundreds of thousands of products, which is slow, expensive, and hard to undo in a shared Project. Bound the first run to a small representative sample, and reserve full-catalog runs for the Import API path.

With that sample, prove the following:

• The Products, Categories, Prices, and Inventory exist with the expected keys, localized values, and references.
• Re-running the same sample changes nothing and creates no duplicates, which confirms the upsert is idempotent.
• A record changed in the source reaches commercetools within the agreed window.
• A field another system owns remains unchanged after an update from a different source.
• A product discontinued in the source produces the agreed outcome, such as unpublish or deactivate, rather than remaining sellable.
• Reconciliation detects a deliberately skipped update and repairs it.

Troubleshoot observable symptoms

Match the symptom you observe to its likely cause and resolution: