> AI agents: this is one page from PostHog's docs. Full index of Markdown docs for LLMs: https://posthog.com/llms.txt

# Linking commercetools as a source

Canonical URL: https://posthog.com/docs/data-pipelines/sources/commercetools

> **Cloud region:** This page uses US Cloud hosts. For an EU Cloud project, use `https://eu.posthog.com` instead of `https://us.posthog.com` or `https://app.posthog.com` (app host for links).

## On this page

- [Adding a data source](#adding-a-data-source)
- [Creating an API client](#creating-an-api-client)
- [Configuration](#configuration)
- [Supported tables](#supported-tables)
- [Sync modes](#sync-modes)
- [Available tables](#available-tables)

**Beta release**

This source is currently in **beta**. It works end to end, but you may still hit rough edges. [Let us know](https://us.posthog.com/#panel=support%3Asupport%3Adata_warehouse%3A%3Atrue) if you do.

![](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`

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

![](https://res.cloudinary.com/dmukukwp6/image/upload/wizard_3f8bb7a240.png)Let AI connect your sources for you

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 | — |
| `shopping_lists` | A shopping list, used to model wishlists and saved carts a customer keeps before checkout. | Incremental, Full refresh | lastModifiedAt | — |
| `product_projections` | A projected (current or staged) view of a product, ready for storefront display. | Incremental, Full refresh | lastModifiedAt | — |
| `product_types` | A product type defining the common custom attributes shared by many products. Products and product projections reference the product type they were created from. | Incremental, Full refresh | lastModifiedAt | — |
| `variants` | A Product Variant managed as a standalone resource, with its current (published) and staged (draft) data. Only available for projects using the Modular catalog model, where product projections carry no variants. | 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 | — |
| `standalone_prices` | A price held outside the product it applies to, matched to a product variant by SKU. | Incremental, Full refresh | lastModifiedAt | — |
| `stores` | A store, modelling the physical or digital context a customer shops in. Orders and carts reference the store they belong to. | Incremental, Full refresh | lastModifiedAt | — |
| `channels` | A channel, representing a source or destination such as a warehouse or a physical store. Inventory entries and orders reference channels as supply and distribution channels. | Incremental, Full refresh | lastModifiedAt | — |
| `customer_groups` | A customer group used to segment customers, for example for group-specific prices. Customers, carts and orders reference the group they belong to. | Incremental, Full refresh | lastModifiedAt | — |
| `states` | A state in a custom state machine, used to model the lifecycle of orders, line items, products, reviews and payments. | Incremental, Full refresh | lastModifiedAt | — |
| `messages` | A change event recorded for a resource, such as OrderStateChanged or CustomerCreated. Only recorded while the Messages Query feature is enabled for the project, and only kept until the project's message retention period expires, so this table covers that window rather than all history. | 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 |