> 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/marketing/appfigures/best-practices.md).

# Best Practices

## Recommended setup

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th></tr></thead><tbody><tr><td><strong>Start with a focused entity</strong></td><td>Don't pull all entities at once. Start with the one most relevant to your goal — Reports revenues for finance, Reports sales for growth tracking — then add others as needed.</td></tr><tr><td><strong>Use Group by: date for time-series analysis</strong></td><td>The default grouping is by product, which collapses all dates into totals. Switch to <code>date</code> if you want to build trend charts or track changes over time.</td></tr><tr><td><strong>Set your store parameter explicitly</strong></td><td>The search_store parameter defaults to Apple. If you track apps on Google Play or other stores, set this explicitly so you don't accidentally miss data.</td></tr><tr><td><strong>Join revenue and ad spend data</strong></td><td>Use Coupler.io's Join transformation to merge Reports revenues and Reports adspends on the product + date dimensions. This gives you a single table to calculate ROAS without manual spreadsheet work.</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>Account for store reporting delays</strong></td><td>Apple and Google typically finalize data 24–72 hours after the day ends. Schedule refreshes for mid-morning (rather than midnight) to reduce the chance of pulling incomplete day-of data.</td></tr><tr><td><strong>Use Append for multi-account reporting</strong></td><td>If you manage apps across multiple Appfigures accounts, create separate data flows for each and use the Append transformation to combine them into one destination sheet or table.</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>Limit date ranges for large catalogs</strong></td><td>If you have many apps, pulling a full year of daily data in one run can be slow or hit rate limits. Use a rolling 30–90 day window and store historical data incrementally.</td></tr><tr><td><strong>Use the Statuses entity as a health check</strong></td><td>Before debugging missing data in your reports, pull the Statuses entity first. It quickly tells you whether Appfigures has successfully synced each connected store — saving time on unnecessary troubleshooting.</td></tr></tbody></table>

## Common pitfalls

{% hint style="danger" %}
**Don't compare proceeds to gross revenue.** Appfigures reports both, and mixing them up leads to significant revenue discrepancies — especially when comparing against store dashboards that show gross figures.
{% endhint %}

{% columns %}
{% column %}
**Do**

* Set `group_by` to `date` when building time-series dashboards
* Verify the `search_store` parameter matches your target store
* Check the Statuses entity when data looks incomplete
* Join revenue + ad spend data at the product level for ROI analysis
  {% endcolumn %}

{% column %}
**Don't**

* Pull all 11 entities in a single data flow without a clear use case
* Use the default `group_by: product` setting when you need daily trends
* Assume today's data is final — store reporting lags by 24–72 hours
* Mix proceeds and gross revenue metrics in the same calculation
  {% 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/marketing/appfigures/best-practices.md?ask=<question>&goal=<endgoal>
```

`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.
