> 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/best-practices.md).

# Best Practices

## Recommended setup

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th></tr></thead><tbody><tr><td><strong>Use least-privilege API scopes</strong></td><td>Create a dedicated API client for Coupler.io with only the view scopes you need. Avoid using a client with manage or admin scopes for read-only reporting.</td></tr><tr><td><strong>Set a meaningful start date</strong></td><td>Use the date picker to set a start date that matches your reporting window. For ongoing reporting, set it to the beginning of your current fiscal year or campaign period — not the beginning of time.</td></tr><tr><td><strong>Join orders and payments for revenue reconciliation</strong></td><td>Use Coupler.io's Join transformation to combine the Orders and Payments entities on order ID. This gives you a single row per order with both fulfillment and payment status — ideal for finance reporting.</td></tr></tbody></table>

## Data refresh and scheduling

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th></tr></thead><tbody><tr><td><strong>Run a successful manual sync first</strong></td><td>Always complete a manual run before setting a schedule. This confirms your credentials, scopes, and date range are correct before automated refreshes kick in.</td></tr><tr><td><strong>Sync orders more frequently than products</strong></td><td>Order and payment data changes constantly, while your product catalog is more stable. Set shorter refresh intervals for orders/payments and longer ones for products and discount codes.</td></tr></tbody></table>

## Performance optimization

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th></tr></thead><tbody><tr><td><strong>Split large catalogs into separate data flows</strong></td><td>If your Commercetools project has a very large product catalog, consider creating separate data flows for products vs. transactional entities (orders, payments). This makes each run faster and easier to troubleshoot.</td></tr><tr><td><strong>Use Append for multi-project reporting</strong></td><td>If your brand operates multiple Commercetools projects (e.g., separate regions or storefronts), use Coupler.io's Append transformation to consolidate data from all projects into a single destination table.</td></tr></tbody></table>

## Common pitfalls

{% hint style="danger" %}
Do not use an API client with manage or admin scopes for your Coupler.io integration. If those credentials are ever exposed, an attacker could modify your store data. Read-only view scopes are sufficient for all Coupler.io exports.
{% endhint %}

{% columns %}
{% column %}

### Do

* Create a dedicated read-only API client for Coupler.io
* Match the region exactly as it appears in your Merchant Center project settings
* Divide price fields by 100 when displaying currency values in reports
* Use Join transformation to link orders with customers or payments
  {% endcolumn %}

{% column %}

### Don't

* Reuse an API client that's already in use by other integrations — credential rotation will break your data flow
* Set your start date to the earliest possible date on every sync — this slows down runs unnecessarily
* Assume localized fields like product names will appear as plain strings — check the locale key structure first
  {% endcolumn %}
  {% endcolumns %}


---

# 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/best-practices.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.