> 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). # Commercetools Best Practices Get the most from your Commercetools exports — API key scopes, date filters, and multi-entity join tips for cleaner reporting. ## Recommended setup


Use least-privilege API scopes	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.
Set a meaningful start date	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.
Join orders and payments for revenue reconciliation	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.

## Data refresh and scheduling


Run a successful manual sync first	Always complete a manual run before setting a schedule. This confirms your credentials, scopes, and date range are correct before automated refreshes kick in.
Sync orders more frequently than products	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.

## Performance optimization


Split large catalogs into separate data flows	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.
Use Append for multi-project reporting	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.

## 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 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/best-practices.md?ask=&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.