Best Practices

Recommended setup

Use a dedicated integration token

Create a Magento integration specifically for Coupler.io with read-only access. Avoid using admin user tokens — they inherit full permissions and can't be scoped to specific resources.

Scope permissions tightly

Only grant access to the Magento resources you actually need. For a revenue dashboard, that might just be Sales and Customers — no need to expose Catalog or Inventory if you're not using them.

Set a sensible start date

For large stores, pulling all historical orders from the beginning can be slow and noisy. Use the date picker to set a start date that covers your analysis window — 12–24 months is usually enough for trend reporting.

Join Orders with Invoices and Shipments

Orders alone don't tell the full fulfillment story. Use Coupler.io's Join transformation to combine Orders, Invoices, and Shipments on order_id for end-to-end revenue and logistics visibility.

Data refresh and scheduling

Match refresh frequency to order volume

High-volume stores processing hundreds of orders per day benefit from hourly syncs of the Orders entity. Lower-volume stores can typically use daily refreshes without missing anything actionable.

Sync slow-changing entities less frequently

Entities like Products, Tax rates, Customer groups, and Store views change rarely. A daily or weekly refresh is sufficient — syncing them hourly wastes API calls and slows down your data flow.

Append multi-store data

If you run multiple Magento websites or store views, set up separate sources for each and use Coupler.io's Append transformation to consolidate them into one dataset for cross-store reporting.

Performance optimization

Don't pull Inventory source items on every sync

This entity can be very large for stores with many SKUs across multiple warehouse locations. Pull it on a separate schedule (e.g., daily) rather than including it in your high-frequency orders sync.

Use BigQuery for large datasets

If your store has years of order history or a large product catalog, send data to BigQuery rather than Google Sheets. Sheets has row limits that can cause problems with multi-year exports of high-volume stores.

Common pitfalls

Don't rely on the total_refunded field on the Orders entity for refund reporting — it's a summary value that may not reflect partial refunds accurately. Pull the Creditmemos entity and join it to Orders for reliable refund data.

Do

• Use base_grand_total for consistent multi-currency reporting
• Join Inventory source items to Products on SKU to get readable inventory reports
• Test your integration token permissions before scheduling a sync
• Use the Aggregate transformation to roll up order totals by day, week, or store view

Don't

• Use an admin user token instead of a scoped integration token
• Pull all entities in a single data flow if you only need order data
• Mix grand_total and base_grand_total in the same revenue calculation
• Ignore the API version field — using the wrong version can return incomplete or malformed data