> For the complete documentation index, see [llms.txt](https://docs.coupler.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.coupler.io/sources/category/ecommerce/commercetools.md).

# Commercetools

Connect Commercetools to Google Sheets, BigQuery, or AI tools via Coupler.io. Export orders, products, customers, and payments in minutes.

Commercetools is a cloud-native, headless commerce platform used by mid-market and enterprise brands to manage their product catalog, orders, customers, and payments. It provides a flexible API-first approach to building commerce experiences across any channel.

Connecting Commercetools to Coupler.io lets you pull your store data into spreadsheets, BI tools, or AI assistants — without writing a single line of code.

**Why connect Commercetools to Coupler.io?**

* Sync orders, customers, products, payments, and discount codes into Google Sheets, Excel, BigQuery, Looker Studio, or AI destinations like ChatGPT, Claude, or Gemini
* Combine multiple entities — for example, join orders with payments to track revenue and fulfillment in one view
* Schedule automatic refreshes so your reports always reflect the latest store data
* Append data from multiple Commercetools projects into a single destination for consolidated reporting

## Prerequisites

Before connecting, make sure you have:

* A Commercetools account with at least one active project
* A **Client ID**, **Client Secret**, **Project Key**, and **Region** for your project — these come from an API client you create in the Commercetools Merchant Center
* The API client must have read scopes for the entities you want to export (e.g., `view_orders`, `view_customers`, `view_products`)

## Quick start

{% hint style="success" %}
Create your API client in the Commercetools Merchant Center under **Settings → Developer settings → API clients**. Give it only the view scopes you need — this keeps access minimal and secure.
{% endhint %}

{% stepper %}
{% step %}
**Create a new data flow in Coupler.io** and select **Commercetools** as the source.
{% endstep %}

{% step %}
**Enter your API credentials.** You'll need your Client ID, Client Secret, Project Key, and Region. These are available on the API client detail page in the Merchant Center.
{% endstep %}

{% step %}
**Select the entity** you want to export — Customers, Orders, Products, Payments, or Discount codes.
{% endstep %}

{% step %}
**Set a start date** using the date picker to control how far back Coupler.io pulls data.
{% endstep %}

{% step %}
**Choose your destination** — Google Sheets, Excel, BigQuery, Looker Studio, or an AI destination such as Claude, ChatGPT, or Gemini.
{% endstep %}

{% step %}
**Run the data flow manually** to confirm everything is connected and data is loading correctly.
{% endstep %}
{% endstepper %}

## Available entities

| Entity         | Description                                                           |
| -------------- | --------------------------------------------------------------------- |
| Customers      | Contact details, preferences, and account data                        |
| Orders         | Line items, pricing, shipping, and fulfillment status                 |
| Payments       | Transactions, payment methods, and processing status                  |
| Products       | Catalog data including descriptions, pricing, and inventory           |
| Discount codes | Promotional codes, discount rules, usage counts, and validity periods |

## Commercetools data overview

Commercetools exposes five entities through Coupler.io, covering the core of your commerce operations — from catalog management to transactional data.

## Entities

| Entity         | What it contains                                                          |
| -------------- | ------------------------------------------------------------------------- |
| Customers      | Account info, contact details, addresses, and customer group membership   |
| Orders         | Order lifecycle data including line items, totals, shipping, and state    |
| Payments       | Payment records linked to orders, including method and transaction status |
| Products       | Full catalog data — variants, pricing, attributes, categories, and stock  |
| Discount codes | Code strings, associated cart discounts, usage limits, and active periods |

## Available fields

#### Customers

| Field                    | Description                                    |
| ------------------------ | ---------------------------------------------- |
| `id`                     | Unique customer identifier                     |
| `email`                  | Customer email address                         |
| `firstName` / `lastName` | Customer name                                  |
| `customerGroup`          | Group the customer belongs to (e.g., B2B, VIP) |
| `addresses`              | Billing and shipping address records           |
| `createdAt`              | Account creation timestamp                     |
| `lastModifiedAt`         | Last update timestamp                          |
| `isEmailVerified`        | Whether the email has been verified            |

#### Orders

| Field           | Description                                          |
| --------------- | ---------------------------------------------------- |
| `id`            | Unique order identifier                              |
| `orderNumber`   | Human-readable order number                          |
| `customerId`    | Reference to the placing customer                    |
| `lineItems`     | Array of purchased items with quantities and prices  |
| `totalPrice`    | Order total including currency                       |
| `orderState`    | Current state (Open, Confirmed, Complete, Cancelled) |
| `shipmentState` | Shipping status (Pending, Shipped, Delivered, etc.)  |
| `paymentState`  | Payment status (Pending, Paid, Failed, etc.)         |
| `createdAt`     | Order creation timestamp                             |

#### Payments

| Field               | Description                                        |
| ------------------- | -------------------------------------------------- |
| `id`                | Unique payment identifier                          |
| `amountPlanned`     | Intended payment amount and currency               |
| `paymentMethodInfo` | Payment method name and payment interface          |
| `transactions`      | Individual transaction records with type and state |
| `paymentStatus`     | Overall status of the payment                      |
| `createdAt`         | Payment creation timestamp                         |

#### Products

| Field                              | Description                                         |
| ---------------------------------- | --------------------------------------------------- |
| `id`                               | Unique product identifier                           |
| `key`                              | User-defined product key                            |
| `masterData.current.name`          | Localized product name                              |
| `masterData.current.slug`          | URL slug                                            |
| `masterData.current.masterVariant` | Master variant including SKU, price, and attributes |
| `masterData.current.variants`      | Additional variants                                 |
| `masterData.current.categories`    | Category references                                 |
| `productType`                      | Reference to the product type schema                |

#### Discount codes

| Field                      | Description                                  |
| -------------------------- | -------------------------------------------- |
| `id`                       | Unique discount code identifier              |
| `code`                     | The actual discount code string              |
| `cartDiscounts`            | Associated cart discount rules               |
| `isActive`                 | Whether the code is currently active         |
| `maxApplications`          | Maximum number of times the code can be used |
| `applicationCount`         | How many times the code has been applied     |
| `validFrom` / `validUntil` | Validity window for the code                 |

## Common field combinations

* **Revenue reporting**: Join `orders` (`totalPrice`, `orderState`) with `payments` (`paymentStatus`, `amountPlanned`) using the order ID to reconcile confirmed revenue
* **Catalog performance**: Combine `products` with `orders` line items to see which SKUs are selling
* **Promotion analysis**: Join `discount_codes` (`code`, `applicationCount`, `maxApplications`) with `orders` to measure promo impact on order value
* **Customer segmentation**: Use `customers` with `customerGroup` and join to `orders` to compare spend across B2B vs. B2C segments

## Use cases by role

{% tabs %}
{% tab title="Ecommerce managers" %}

* Track order state distribution (Open vs. Complete vs. Cancelled) in a live Google Sheets dashboard
* Monitor fulfillment bottlenecks by filtering orders where `shipmentState` is Pending
* Use Aggregate transformation to calculate average order value by customer group
  {% endtab %}

{% tab title="Marketing teams" %}

* Analyze discount code redemption rates and compare against order volume during campaign periods
* Segment customers by `customerGroup` to build targeted re-engagement lists
* Feed product catalog data into ChatGPT or Claude to generate automated product descriptions
  {% endtab %}

{% tab title="Finance teams" %}

* Reconcile `payments` transaction data against `orders` totals in BigQuery
* Report on failed or pending payment states to identify revenue at risk
* Use Append transformation to consolidate orders from multiple Commercetools projects into a single dataset
  {% endtab %}
  {% endtabs %}

## Platform-specific notes

* Commercetools returns nested JSON objects (e.g., `lineItems`, `transactions`, `variants`) — Coupler.io flattens these for spreadsheet destinations, but you may need to parse them in BigQuery
* Localized fields (like product names and slugs) are returned as objects with locale keys — check which locale your project uses
* The `start_date` filter applies to `createdAt` for most entities — historical data before that date won't be included
* Commercetools uses its own regional API endpoints — make sure the region you enter in Coupler.io matches your project's region exactly

## Commercetools common issues

### Connection issues

<details>

<summary>Authentication failed — invalid Client ID or Client Secret</summary>

Double-check that you copied the Client ID and Client Secret from the correct API client in the Merchant Center. These values are only shown once when the client is created — if you didn't save them, you'll need to create a new API client and use its credentials.

</details>

<details>

<summary>Wrong region causing connection failure</summary>

Commercetools hosts projects in multiple regions (e.g., `us-central1.gcp`, `eu-west-1.aws`). If the region you enter doesn't match your project's region, authentication will fail. You can find your project's region in the Merchant Center under **Settings → Project settings**.

</details>

<details>

<summary>Project key not found</summary>

Make sure the Project Key you enter is the technical key from your Commercetools project, not the display name. It's visible in the Merchant Center URL and under **Settings → Project settings**.

</details>

### Missing data

<details>

<summary>No data returned for a specific entity</summary>

Check that your start date is set early enough to capture existing records. If the start date is set to today, only records created from that point forward will be returned. Also verify that the entity actually contains data in your Commercetools project.

</details>

<details>

<summary>Only partial order history is returned</summary>

Commercetools API may paginate large datasets. Use the date picker to narrow the start date range for your first run if you're dealing with a very large catalog or order history. Once your initial export is complete, incremental refreshes will only pull new records.

</details>

### Permission errors

<details>

<summary>Access denied for an entity (e.g., orders or customers)</summary>

Each entity requires a specific read scope on the API client. Check that your API client has the relevant scopes:

* Orders → `view_orders`
* Customers → `view_customers`
* Products → `view_products`
* Payments → `view_payments`
* Discount codes → `view_orders` (discount codes fall under order management)

If a scope is missing, edit the API client in the Merchant Center or create a new one with the correct scopes.

</details>

### Data discrepancies

<details>

<summary>Order totals in Coupler.io don't match Merchant Center reports</summary>

Commercetools stores prices as integers in the smallest currency unit (e.g., cents). If you're seeing unexpectedly large numbers, divide by 100 to convert to the standard currency unit. This is expected behavior from the API.

</details>

<details>

<summary>Product names or slugs appear as objects, not plain text</summary>

Localized fields in Commercetools are returned as objects with locale keys (e.g., `{"en-US": "Blue T-Shirt"}`). In spreadsheet destinations, look for the specific locale column that matches your store's default language.

</details>

### Rate limits

<details>

<summary>Data flow fails with a rate limit or throttling error</summary>

Commercetools enforces API rate limits per project. If you're running multiple data flows simultaneously against the same project, try staggering their schedules. Reducing the date range in your start date setting can also help by limiting the volume of data requested in a single run.

</details>

## Commercetools FAQ

<details>

<summary>What entities can I export from Commercetools?</summary>

Coupler.io supports five Commercetools entities: Customers, Orders, Payments, Products, and Discount codes. Each entity is set up as a separate source within a data flow, and you can combine them using Join or Append transformations.

</details>

<details>

<summary>How do I find my Commercetools API credentials?</summary>

Go to your Commercetools Merchant Center and navigate to **Settings → Developer settings → API clients**. Create a new client with the view scopes you need, and copy the Client ID, Client Secret, Project Key, and Region. Note that the Client Secret is only shown once — save it immediately.

</details>

<details>

<summary>How far back can I pull historical data?</summary>

You control this with the start date setting. Use the date picker to set any past date — Coupler.io will pull all records created from that date onward. There's no hard limit enforced by Coupler.io, but very large date ranges on busy stores may take longer to complete on the first run.

</details>

<details>

<summary>Can I combine data from Orders and Payments in one export?</summary>

Yes. Add both Orders and Payments as sources within the same data flow, then use the Join transformation to link them on the order ID field. This gives you a unified view of order state and payment status in a single destination sheet or table.

</details>

<details>

<summary>Can I consolidate data from multiple Commercetools projects?</summary>

Yes. Create a separate source for each project (each with its own API credentials) and use the Append transformation to stack the results into one destination. This is useful if you run separate regional storefronts or brand projects within Commercetools.

</details>

<details>

<summary>Why do product prices look like very large numbers?</summary>

Commercetools stores monetary values as integers in the smallest currency unit (cents for USD/EUR). A value of `9900` means $99.00. Divide price fields by 100 in your spreadsheet or BI tool to display them correctly.

</details>

<details>

<summary>Can I send Commercetools data to an AI tool like ChatGPT or Claude?</summary>

Yes. When choosing a destination in Coupler.io, you can select AI destinations including ChatGPT, Claude, Gemini, Cursor, Perplexity, and OpenClaw. This is useful for tasks like generating product descriptions from catalog data or summarizing order trends.

</details>

<details>

<summary>Does Coupler.io support incremental syncs for Commercetools?</summary>

Yes. After your initial run, Coupler.io pulls only new or updated records based on the start date and internal sync state, rather than re-importing everything from scratch each time.

</details>

{% hint style="info" %}
For details on available fields and metric combinations, see [Data Overview](#commercetools-data-overview). For connection errors and permission issues, visit [Common Issues](#commercetools-common-issues).
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.coupler.io/sources/category/ecommerce/commercetools.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.