Sales

The /reports/sales resource provides comprehensive access to sales reports. Reports can be generated in a variety of formats.

The main resource gives you a single combined result across the filter parameters you select. The result can be limited by dates, products, countries and some other parameters.

Using the group_by parameter, you can get a report broken down by products, countries, dates, stores, or any combination thereof.

Scope: All of the resources in this route require read access in the private scope (private:read).

Getting “All Time” totals

A very common use case is to get all the data for an app and add it up for an “All time total”.

If you don’t provide start_date and end_date and aren’t using a group_by (for the routes that accept a group_by) that includes ‘dates’ you’ll get a sum of all the available data.

For some products, such as free apps from the Android Market, this will give complete “all time” data set, and not just for the data that’s been imported into the Appfigures account. It may not agree with actually summing up individual days because of inconsistencies in Google’s data.

Getting Simple Totals

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}

Arguments

Argument Type Description
start_date Date (yyyy-mm-dd) Date, inclusive, to start reporting from. If you specify a granularity other than daily this will be rounded down to the nearest period. default: a long, long time ago.
end_date Date (yyyy-mm-dd) Date, inclusive, to stop reporting. If you specify a granularity other than daily this will be rounded up to the nearest period. default: distant future.
group_by List One or more pivots separated by a comma (,). Available pivots: products, countries, dates, stores, and device.
granularity Enum (daily | weekly | monthly | yearly) How to group dates. This affects how start_date and end_date are rounded (they snap to lower and upper barriers of the type given by this parameter) default: daily

Note: the daily and weekly granularities are limited to a maximum of 30 and 365 days per request respectively.
products List (productId | productId1, productId2, …) specific products to include in the response, default: all active products in account
countries List (isoCode | isoCode1;isoCode2;isoCodeN) Countries to limit the report to (can be taken from /data/countries, default: include all countries)
dataset Enum (none | financial ) If this is set to financial, use financial reports. This only applies to Apple products, default: none
devices Enum (handheld | tablet | desktop | tv) Filter results by device. Separate multiple devices with a comma. Watch is not currently supported.
include_inapps Bool (true | false) If set to true any products given in product_ids will have their children automatically selected as well. default: false)
format Enum Output format: JSON or CSV. Defaults to JSON.
Note: When format=csv is given, complex fields will be serialized as ids or otherwise simplified representations to prevent excessive repetition.

Response

downloads An int representing the total number of downloads.
net_downloads An int representing the number of downloads – 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 The number of times the selected apps were removed from a device they were installed on.

Note: This metric is 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 downloadsedu_downloadsbusiness_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 revenueedu_revenuebusiness_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_revenuegross_edu_revenuegross_business_revenue.
pre_orders An int representing the number of orders for a pre-released app. Pre-orders do not count towards downloads until the app is released, at which point the downloads (and subsequent revenue, if applicable) will count towards downloads and revenue separately..

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

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}

Arguments

Argument Type Description
start_date Date (yyyy-mm-dd) Date, inclusive, to start reporting from. If you specify a granularity other than daily this will be rounded down to the nearest period. default: a long, long time ago.
end_date Date (yyyy-mm-dd) Date, inclusive, to stop reporting. If you specify a granularity other than daily this will be rounded up to the nearest period. default: distant future.
group_by List One or more pivots separated by a comma (,). Available pivots: products, countries, dates, stores, and device.
granularity Enum (daily | weekly | monthly | yearly) How to group dates. This affects how start_date and end_date are rounded (they snap to lower and upper barriers of the type given by this parameter) default: daily

Note: the daily and weekly granularities are limited to a maximum of 30 and 365 days per request respectively.
products List (productId | productId1, productId2, …) specific products to include in the response, default: all active products in account
countries List (isoCode | isoCode1;isoCode2;isoCodeN) Countries to limit the report to (can be taken from /data/countries, default: include all countries)
dataset Enum (none | financial ) If this is set to financial, use financial reports. This only applies to Apple products, default: none
devices Enum (handheld | tablet | desktop | tv) Filter results by device. Separate multiple devices with a comma. Watch is not currently supported.
include_inapps Bool (true | false) If set to true any products given in product_ids will have their children automatically selected as well. default: false)
format Enum Output format: JSON or CSV. Defaults to JSON.
Note: When format=csv is given, complex fields will be serialized as ids or otherwise simplified representations to prevent excessive repetition.

Response

The response depends on the specified group_by given. No matter which group_by, the deepest part of the representation is the following leaf:

downloads An int representing the total number of downloads.
re_downloads An int representing the total number of downloads that were reinstalls or subsequent installs after an app was initially installed.
net_downloads An int representing the number of downloads – returns.
updates An int representing the total number of updates.
revenue A float representing the total revenue 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.
returns An int representing the total number of returns.
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.
gross_returns_amount A float representing the amount of money refunded to customers, 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 uninstalled from a user’s device.

Note: This metric is only available for Android apps sold through Google Play.

date (optional) A string (yyyy-MM-dd) representing the date of the leaf. This is only returned when the `group_by` includes `date`.
product_id (optional) The product’s ID. This is only returned when the `group_by` includes `product`.
iso (optional) The ISO code for the current leaf’s country. This is only returned when the `group_by` includes `country`.
country (optional) The leaf’s country name. This is only returned when the `group_by` includes `country`.
product (optional) A full representation of the leaf’s product. This is only returned when the `group_by` includes `product`.

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

// 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

// GET /reports/sales/?group_by=products&start=2017-05-20&end=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

Response: structure of products mapped to dates mapped to sales information

// GET /reports/sales?group_by=products,dates&start_date=-30

{
  "12345": {
    "2020-09-03": {
      "date": "2016-11-24",
      "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": "2016-11-24",
      "product_id": 123456,
      "downloads": 28,
      "re_downloads": 30,
      "net_downloads": 29,
      "updates": 6,
      "revenue": "19.02",
      "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

Response: structure of dates mapped to products mapped to sales information

// GET /reports/sales?group_by=dates,products?start_date=-30

{
  "2020-09-03": {
    "12345": {
      "date": "2016-11-24",
      "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": {
    "294956": {
      "date": "2016-11-25",
      "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,
    },
    ...
  },
  ...
}