# 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 one data flow per entity group</strong></td><td>Split structural entities (Families, Attributes, Channels) from transactional ones (Products) into separate flows. Structural data changes rarely — syncing it daily is overkill and wastes API quota.</td></tr><tr><td><strong>Join Products with Families in your destination</strong></td><td>The Products entity alone doesn't tell you the full attribute structure. Add Families as a second source and use Coupler.io's Join transformation on the family code to enrich product records with family-level rules.</td></tr><tr><td><strong>Use Append for multi-environment exports</strong></td><td>If you have staging and production Akeneo instances, add both as sources in a single data flow and use Append to combine them. Tag each row with an environment label so you can filter in your destination.</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>Sync Products more frequently than reference data</strong></td><td>Product records (descriptions, images, pricing) change often. Reference entities like Currencies, Locales, and Measure families almost never change — a weekly refresh is plenty for those.</td></tr><tr><td><strong>Run a successful manual sync before scheduling</strong></td><td>Always complete a manual run first to confirm your credentials and entity selection return the expected data. Only then set up a schedule to avoid silent failures.</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>Export reference entities separately</strong></td><td>Pulling Attributes, Attribute groups, and Families in the same flow as a large product catalog increases sync time significantly. Keep them in a dedicated flow that runs less frequently.</td></tr><tr><td><strong>Use BigQuery or another warehouse for large catalogs</strong></td><td>If your catalog exceeds a few thousand products with many localized attribute values, Google Sheets will hit row limits quickly. Route the Products entity to BigQuery and use Looker Studio on top for reporting.</td></tr></tbody></table>

## Common pitfalls

{% hint style="danger" %}
Do not reuse a single Akeneo API connection across multiple Coupler.io data flows with different permission requirements. If the connection is regenerated or its role is changed, all flows using it will break at once.
{% endhint %}

{% columns %}
{% column %}

#### Do

* Create a dedicated Akeneo API connection specifically for Coupler.io exports
* Check that the connection role has read access to every entity you plan to sync
* Join Products with Categories to get the full hierarchy path per product
  {% endcolumn %}

{% column %}

#### Don't

* Use admin credentials for the API connection — a read-only role is safer and sufficient
* Expect `values` to be flat — attribute values are nested by locale and channel scope
* Pull all entities in one flow if your catalog is large — split them to stay within rate limits
  {% endcolumn %}
  {% endcolumns %}