Common Issues

Connection issues

Authentication failed — invalid Client ID or Client Secret

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.

Wrong region causing connection failure

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.

Project key not found

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.

Missing data

No data returned for a specific entity

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.

Only partial order history is returned

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.

Permission errors

Access denied for an entity (e.g., orders or customers)

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.

Data discrepancies

Order totals in Coupler.io don't match Merchant Center reports

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.

Product names or slugs appear as objects, not plain text

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.

Rate limits

Data flow fails with a rate limit or throttling error

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.