> 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/data-overview.md).

# 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


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.