# Linking commercetools as a source - Docs

![](https://res.cloudinary.com/dmukukwp6/image/upload/texture_tan_9608fcca70)

![](https://res.cloudinary.com/dmukukwp6/image/upload/texture_tan_dark_a92b0e022d)

Let AI connect your sources for you

Skip the manual setup — run this in your project and the wizard auto-detects your databases and APIs and connects them to PostHog.

`npx @posthog/wizard warehouse`

[Learn more](/wizard.md)

![PostHog Wizard hedgehog](https://res.cloudinary.com/dmukukwp6/image/upload/wizard_3f8bb7a240.png)

**Alpha release**

The commercetools source is currently in alpha. It has been tested against the commercetools API documentation but not yet battle-tested with live production workloads. If you run into issues, please let us know.

The commercetools connector syncs your commerce data into PostHog, including orders, customers, payments, carts, product projections, categories, discount codes, and inventory.

## Adding a data source

1.  Go to the [Data pipeline page](https://app.posthog.com/data-management/sources) and select the **Sources** tab.
2.  Click **\+ New source** and select commercetools by clicking the **Link** button.
3.  Select your **Region** from the dropdown. This must match the region your commercetools project is hosted in:

| Label | Value |
| --- | --- |
| North America (GCP, us-central1) | us-central1.gcp |
| North America (AWS, us-east-2) | us-east-2.aws |
| Europe (GCP, europe-west1) | europe-west1.gcp |
| Europe (AWS, eu-central-1) | eu-central-1.aws |
| Australia (GCP, australia-southeast1) | australia-southeast1.gcp |

4.  Enter your **Project key**. You can find this in the commercetools Merchant Center under **Settings** > **Developer settings**, or on the API client details page alongside your generated credentials.
5.  Enter your **Client ID** and **Client secret**. These come from an API client you create in the Merchant Center (see [Creating an API client](#creating-an-api-client) below).
6.  Select the tables you want to import.
7.  Click **Import**.

The data warehouse then starts syncing your commercetools data. You can see details and progress in the [data pipeline sources tab](https://app.posthog.com/data-management/sources).

## Creating an API client

To connect commercetools to PostHog, create a dedicated API client with read-only scopes:

1.  In the commercetools Merchant Center, go to **Settings** > **Developer settings**.
2.  Click **Create new API client**.
3.  Give it a descriptive name (e.g., "PostHog sync").
4.  Grant the following **view** scopes depending on which tables you want to sync:

| Table | Required scope |
| --- | --- |
| orders | view_orders |
| customers | view_customers |
| payments | view_payments |
| carts | view_orders |
| product_projections | view_products |
| categories | view_categories |
| discount_codes | view_discount_codes |
| inventory | view_products |

5.  Click **Create API client**.
6.  Copy the **Client ID**, **Client secret**, **Project key**, and **Region** – you'll need all four when linking the source in PostHog.

**Save your client secret**

The client secret is only shown once when you create the API client. If you lose it, you'll need to create a new API client.

## Configuration

| Option | Type | Required |
| --- | --- | --- |
| Region | select | Yes |
| Project key | text | Yes |
| Client ID | text | Yes |
| Client secret | password | Yes |

## Supported tables

| Table | Description | Sync method | Incremental field | Primary key |
| --- | --- | --- | --- | --- |
| orders | A confirmed checkout of a cart, representing a purchase made by a customer. | Incremental, Full refresh | lastModifiedAt | — |
| customers | A registered customer account in the commercetools project. | Incremental, Full refresh | lastModifiedAt | — |
| payments | A payment representing money received or refunded for an order. | Incremental, Full refresh | lastModifiedAt | — |
| carts | A shopping cart holding line items a customer intends to purchase. | Incremental, Full refresh | lastModifiedAt | — |
| product_projections | A projected (current or staged) view of a product, ready for storefront display. | Incremental, Full refresh | lastModifiedAt | — |
| categories | A category used to organize products into a navigable hierarchy. | Incremental, Full refresh | lastModifiedAt | — |
| discount_codes | A discount code customers can redeem to apply a cart discount. | Incremental, Full refresh | lastModifiedAt | — |
| inventory | An inventory entry tracking stock quantity for a SKU at a supply channel. | Incremental, Full refresh | lastModifiedAt | — |

## Sync modes

commercetools tables support both incremental and full refresh syncing:

-   **Incremental** – Only imports records modified since the last sync, using the `lastModifiedAt` field. This is the most efficient option for ongoing syncs.
-   **Full refresh** – Re-imports all records from commercetools on every sync.

All tables also support append-only syncing, which adds new records without updating existing ones.

When you enable incremental sync for a table, the first sync performs a full import to establish a baseline. Subsequent syncs only fetch records where `lastModifiedAt` is at or after the last synced value.

## Available tables

All tables use `id` as the primary key and partition data by `createdAt` (monthly).

| Table | Description |
| --- | --- |
| orders | Customer orders and their line items |
| customers | Customer accounts and profiles |
| payments | Payment transactions |
| carts | Active and inactive shopping carts |
| product_projections | Product catalog data (projected view) |
| categories | Product category hierarchy |
| discount_codes | Promotional discount codes |
| inventory | Stock levels across supply channels |

### Community questions

Ask a question

### Was this page useful?

HelpfulCould be better