Best Practices

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

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.

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

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