> 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/adobe-commerce-magento/best-practices.md). # 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 {% hint style="danger" %} 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. {% endhint %} {% columns %} {% column %} #### 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 {% endcolumn %} {% column %} #### 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 {% 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/adobe-commerce-magento/best-practices.md?ask=&goal= ``` `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.