Sales
Use /reports/sales to get your sales reports as JSON or CSV.
By default, you get one combined total for the filters you set. You can filter by date, product, country and more.
Use group_by to break the report down by product, country, date, store, or any combination.
Query String Parameters
Section titled “Query String Parameters”| Argument | Type | Description |
|---|---|---|
| start_date | Date | (yyyy-mm-dd) First date to report on, inclusive. With a granularity other than daily, we round it down to the nearest period. Default: the earliest data available. |
| end_date | Date | (yyyy-mm-dd) Last date to report on, inclusive. With a granularity other than daily, we round it up to the nearest period. Default: the latest data available. |
| group_by | List | One or more pivots, separated by commas. Available pivots: products, countries, dates, stores, and device. With dataset=financial, you can also group by state. Only Apple supports state, and only in the US and Canada. We ignore other stores and countries when you use it. |
| granularity | Enum | (daily | weekly | monthly | yearly) How to group dates. This also sets how we round start_date and end_date: they snap to the start and end of the period. Default: daily Note: Daily requests are limited to 30 days, and weekly requests to 365 days. |
| products | List | (productId | productId1, productId2, …) Products to include in the response. Default: all active products in your account. |
| countries | List | (isoCode | isoCode1;isoCode2;isoCodeN) Countries to limit the report to. Get country codes from /data/countries. Default: all countries. |
| dataset | Enum | (none | financial) Set to financial to use financial reports. Applies only to Apple and Google Play products. Default: none. Financial reports require granularity=monthly. |
| devices | Enum | (handheld | tablet | desktop | tv) Filter results by device. Separate multiple devices with commas. Watch isn’t supported. |
| include_inapps | Bool | (true | false) If true, we also include the children (in-app purchases) of any products you pass in products. Default: false. |
| format | Enum | Output format: JSON or CSV. Defaults to JSON. Note: With format=csv, we serialize complex fields as IDs or other simplified values to avoid repetition. |
Common Response Fields
Section titled “Common Response Fields”| Field | Description |
|---|---|
| downloads | An int representing the total number of downloads. |
| net_downloads | An int representing downloads minus returns. |
| app_downloads | An int representing the number of downloads for the app, not including any in-app purchases (even if specified by ID). |
| re_downloads | An int representing the total number of downloads that were reinstalls or subsequent installs after an app was initially installed. |
| updates | An int representing the total number of updates. |
| revenue | A float representing the total revenue, after the store’s fee, in the user’s selected currency. |
| app_revenue | A float representing the total revenue from app sales (not including in-app purchases), after the store’s fee, in the user’s selected currency. |
| gross_revenue | A float representing the total revenue before the store’s fee, in the user’s selected currency. |
| gross_app_revenue | A float representing the total revenue from app sales (not including in-app purchases), before the store’s fee, in the user’s selected currency. |
| returns | An int representing the total number of returns. |
| app_returns | An int representing the total number of returns for apps, not including in-app purchases. |
| gifts | An int representing the number of times products in this report were gifted. |
| gift_redemptions | An int representing the number of times products in this report were gifted and then redeemed. |
| promos | An int representing the total number of promo codes used. |
| edu_downloads | An int representing the total number of educational downloads. |
| returns_amount | A float representing the amount of money refunded to customers, after the store’s fee, in the user’s selected currency. |
| app_returns_amount | A float representing the amount of money refunded to customers from app sales (not including in-app purchases), after the store’s fee, in the user’s selected currency. |
| gross_returns_amount | A float representing the amount of money refunded to customers, before the store’s fee, in the user’s selected currency. |
| gross_app_returns_amount | A float representing the amount of money refunded to customers from app sales (not including in-app purchases), before the store’s fee, in the user’s selected currency. |
| edu_revenue | A float representing the revenue from sales to educational institutions (usually discounted), after the store’s fee, in the user’s selected currency. |
| gross_edu_revenue | A float representing the revenue from sales to educational institutions (usually discounted), before the store’s fee, in the user’s selected currency. |
| uninstalls | An int representing the number of times the selected apps were removed from a device they were installed on. Note: Only available for Apple and Google Play. |
| business_downloads | An int representing the number of downloads received through Apple’s Volume Purchase for Business program. |
| business_revenue | A float representing revenue from downloads generated through Apple’s Volume Purchase for Business program, not including the store’s fee. |
| gross_business_revenue | A float representing revenue from downloads generated through Apple’s Volume Purchase for Business program, including the store’s fee. |
| standard_downloads | An int representing downloads generated via the store and not through any purchasing program. This equals downloads - edu_downloads - business_downloads. |
| standard_revenue | A float representing revenue, not including the store’s fee, generated via the store and not through any purchasing program. This equals revenue - edu_revenue - business_revenue. |
| gross_standard_revenue | A float representing revenue, including the store’s fee, generated via the store and not through any purchasing program. This equals gross_revenue - gross_edu_revenue - gross_business_revenue. |
| pre_orders | An int representing the number of orders for a pre-released app. Pre-orders don’t count toward downloads until the app is released. After release, they count toward downloads and revenue (if any) separately. |
Getting “All Time” Totals
Section titled “Getting “All Time” Totals”To get an “all time” total for an app, leave out start_date and end_date, and don’t use a group_by that includes dates. You’ll get a sum of all available data.
For some products, such as free apps from Google Play, this gives you the complete all-time data set, not just the data imported into your Appfigures account. It may not match the sum of individual days because of inconsistencies in Google’s data.
Getting Simple Totals
Section titled “Getting Simple Totals”Request
Section titled “Request”GET /reports/sales/?group_by={group_by}&start_date={start_date}&end_date={end_date}&granularity={granularity}&products={product_ids}&countries={countries}&dataset={dataset}&include_inapps={include_inapps}&format={format}Example
Section titled “Example”// GET /reports/sales/
{ "downloads": 155299, "re_downloads": 133092, "updates": 91156, "returns": 56, "net_downloads": 155243, "promos": 2, "revenue": "26188.63", "gross_revenue": "37412.32", "returns_amount": "609.21", "edu_downloads": 54, "gifts": 36, "gift_redemptions": 0, "edu_revenue": "0.00", "gross_returns_amount": "0.00", "gross_edu_revenue": "0.00", "uninstalls": 1811}Generating a Report by Product, Country, or Date
Section titled “Generating a Report by Product, Country, or Date”Request
Section titled “Request”GET /reports/sales/?group_by={group_by}&start_date={start_date}&end_date={end_date}&granularity={granularity}&products={product_ids}&countries={countries}&dataset={dataset}&include_inapps={include_inapps}&format={format}Response
Section titled “Response”The response always includes the Common Response Fields above. It also includes these fields, depending on your group_by.
| Field | Description |
|---|---|
| date (optional) | The date of the leaf (yyyy-MM-dd). Returned only when group_by includes date. |
| product_id (optional) | The product’s ID. Returned only when group_by includes product. |
| iso (optional) | The ISO code of the leaf’s country. Returned only when group_by includes country. |
| country (optional) | The leaf’s country name. Returned only when group_by includes country. |
| product (optional) | The leaf’s full product object. Returned only when group_by includes product. |
Example Response for Sales by Date Report
Section titled “Example Response for Sales by Date Report”// GET /reports/sales/?group_by=dates
{ "2017-05-28": { "downloads": 233, "re_downloads": 150, "updates": 2, "returns": 0, "net_downloads": 233, "promos": 0, "revenue": "246.97", "gross_revenue": "341.21", "returns_amount": "0", "edu_downloads": 0, "gifts": 0, "gift_redemptions": 0, "edu_revenue": "0.00", "gross_returns_amount": "0.00", "gross_edu_revenue": "0.00", "uninstalls": 11, "date": "2017-05-28" }, . . . "2017-06-07": { "downloads": 64, "re_downloads": 45, "updates": 0, "returns": 0, "net_downloads": 64, "promos": 0, "revenue": "99.48", "gross_revenue": "142.48", "returns_amount": "0", "edu_downloads": 0, "gifts": 0, "gift_redemptions": 0, "edu_revenue": "0.00", "gross_returns_amount": "0.00", "gross_edu_revenue": "0.00", "uninstalls": 8, "date": "2017-06-07" }}Example for Sales by Country Report
Section titled “Example for Sales by Country Report”// GET /reports/sales/?group_by=countries
{ "AE": { "downloads": 840, "re_downloads": 700, "updates": 271, "returns": 0, "net_downloads": 840, "promos": 0, "revenue": "268.28", "gross_revenue": "418.11", "returns_amount": "0", "edu_downloads": 0, "gifts": 0, "gift_redemptions": 0, "edu_revenue": "0.00", "gross_returns_amount": "0.00", "gross_edu_revenue": "0.00", "uninstalls": 91, "country": "UAE", "iso": "AE" }, "AG": { "downloads": 4, "re_downloads": 4, "updates": 1, "returns": 1, "net_downloads": 4, "promos": 0, "revenue": "2.30", "gross_revenue": "3.20", "returns_amount": "0.99", "edu_downloads": 0, "gifts": 0, "gift_redemptions": 0, "edu_revenue": "0.00", "gross_returns_amount": "0.00", "gross_edu_revenue": "0.00", "uninstalls": 0, "country": "Antigua And Barbuda", "iso": "AG" }, . . .}Example for Sales by Product Report
Section titled “Example for Sales by Product Report”// GET /reports/sales/?group_by=products&start_date=2017-05-20&end_date=2017-05-25
{ "12345": { "downloads": 45, "re_downloads": 30, "updates": 0, "returns": 45, "net_downloads": 0, "promos": 0, "revenue": "0.64", "gross_revenue": "0.99", "returns_amount": "501.22", "edu_downloads": 0, "gifts": 0, "gift_redemptions": 0, "edu_revenue": "0.00", "gross_returns_amount": "0.00", "gross_edu_revenue": "0.00", "uninstalls": 4, "product_id": 12345, "product": { "id": 12345, "name": "Awesome app", "developer": "Jeff", "icon": "https://lh3.ggpht.com/jeffs-icon", "vendor_identifier": "com.jeff.mva", "package_name": "com.jeff.mva", "store_id": 2, "store": "google_play", "release_date": "2016-12-01T00:00:00", "added_date": "2016-12-01T20:22:05", "updated_date": "2017-06-04T03:00:00", "version": "4.0.2", "source": { "external_account_id": 77, "added_timestamp": "2012-02-27T19:09:36", "active": true, "hidden": false, "type": "own" }, "type": "unknown", "devices": [ "Handheld" ], "children": [], "features": [], "parent_id": null } }, . . .}Example for Sales by Product and Date Report
Section titled “Example for Sales by Product and Date Report”Response: products mapped to dates, mapped to sales data.
// GET /reports/sales?group_by=products,dates&start_date=-30
{ "12345": { "2020-09-03": { "date": "2020-09-03", "country": null, "iso": null, "product_id": 12345, "downloads": 11, "re_downloads": 10, "net_downloads": 11, "updates": 0, "revenue": "0.00", "gross_revenue": "0.00", "returns_amount": "0", "returns": 0, "gift_redemptions": 0, "promos": 0, "edu_revenue": "0.00", "gross_returns_amount": "0.00", "gross_edu_revenue": "0.00", "uninstalls": 0 }, ... }, "123456": { "2020-09-03": { "date": "2020-09-03", "product_id": 123456, "downloads": 28, "re_downloads": 30, "net_downloads": 29, "updates": 6, "revenue": "19.02", "gross_revenue": "27.20", "returns_amount": "0", "returns": 1, "gift_redemptions": 0, "promos": 0, "edu_revenue": "0.00", "gross_returns_amount": "0.00", "gross_edu_revenue": "0.00", "uninstalls": 2 }, ... }}Example for Sales by Date and Product Report
Section titled “Example for Sales by Date and Product Report”Response: dates mapped to products, mapped to sales data.
// GET /reports/sales?group_by=dates,products&start_date=-30
{ "2020-09-03": { "12345": { "date": "2020-09-03", "product_id": 12345, "downloads": 11, "re_downloads": 15, "net_downloads": 11, "updates": 0, "revenue": "0.00", "gross_revenue": "0.00", "returns_amount": "0", "returns": 0, "gift_redemptions": 0, "promos": 0, "edu_revenue": "0.00", "gross_returns_amount": "0.00", "gross_edu_revenue": "0.00", "uninstalls": 0 }, ... }, "2020-09-04": { "123456": { "date": "2020-09-04", "product_id": 123456, "downloads": 10, "re_downloads": 9, "net_downloads": 10, "updates": 1, "revenue": "0.00", "gross_revenue": "0.00", "returns_amount": "0", "returns": 0, "gift_redemptions": 0, "promos": 0, "edu_revenue": "0.00", "gross_returns_amount": "0.00", "gross_edu_revenue": "0.00", "uninstalls": 0 }, ... }, ...}Generating a Financial Report
Section titled “Generating a Financial Report”Note: Only Apple supports the state group_by, and only in the US and Canada. When you use it, we won’t return data for other stores or countries.
Request
Section titled “Request”GET /reports/sales/?group_by={group_by}&start_date={start_date}&end_date={end_date}&granularity=monthly&products={product_ids}&countries={countries}&dataset=financial&include_inapps={include_inapps}&format={format}Response
Section titled “Response”The response always includes the Common Response Fields above. It also includes these fields, depending on your group_by.
| Field | Description |
|---|---|
| date (optional) | The date of the leaf (yyyy-MM-dd). Returned only when group_by includes date. |
| product_id (optional) | The product’s ID. Returned only when group_by includes product. |
| iso (optional) | The ISO code of the leaf’s country. Returned only when group_by includes country. |
| country (optional) | The leaf’s country name. Returned only when group_by includes country. |
| product (optional) | The leaf’s full product object. Returned only when group_by includes product. |
| state (optional) | The state or province abbreviation for the sale. Returned only when group_by includes state. Apple supports only the US and Canada. |
// GET /reports/sales/?group_by=state&start_date=-10&granularity=monthly&dataset=financial{ "NY": { "downloads": 2, "re_downloads": 0, "uninstalls": 0, "updates": 0, "returns": 0, "net_downloads": 2, "promos": 0, "revenue": "10.00", "returns_amount": "0.00", "edu_downloads": 0, "gifts": 0, "gift_redemptions": 0, "edu_revenue": "0.00", "gross_revenue": "15.60", "gross_returns_amount": "0.00", "gross_edu_revenue": "0.00", "business_downloads": 0, "business_revenue": "0.00", "gross_business_revenue": "0.00", "standard_downloads": 2, "standard_revenue": "10.00", "gross_standard_revenue": "15.60", "app_downloads": 0, "app_returns": 0, "iap_amount": 2, "iap_returns": 0, "subscription_purchases": 0, "subscription_returns": 0, "app_revenue": "0.00", "app_returns_amount": "0.00", "gross_app_revenue": "0.00", "gross_app_returns_amount": "0.00", "iap_revenue": "10.0", "iap_returns_amount": "0.00", "gross_iap_revenue": "103.60", "gross_iap_returns_amount": "0.00", "subscription_revenue": "0.00", "subscription_returns_amount": "0.00", "gross_subscription_revenue": "0.00", "gross_subscription_returns_amount": "0.00", "pre_orders": 0, "state": "NY" }, . . .}