> 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/common-issues.md).

# 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>


---

# 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/common-issues.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.