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 nearset period. default: distant future.
group_by List One or more pivots separated by a comma (,). Available pivots: products, countries, dates, and stores.
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
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.
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, 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.
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 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.

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 nearset period. default: distant future.
group_by List One or more pivots separated by a comma (,). Available pivots: products, countries, dates, and stores.
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
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/products+dates?start_date=2016-11-24end_date=2016-11-31

{
  "12345": {
    "2016-11-24": {
      "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": {
    "2016-11-24": {
      "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/dates+products?start_date=2016-11-24&end_date=2016-11-31

{
  "2016-11-24": {
    "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,
    },
    ...
  },
  "2016-11-25": {
    "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,
    },
    ...
  },
  ...
}

Generating a By Region Sales Report

The sales by region report is only available for iTunes Connect accounts at this time.

Request

GET /reports/sales/regions/?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 nearset period. default: distant future.
group_by List One or more pivots separated by a comma (,). Available pivots: products, countries, dates, and stores.
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
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

region_id The numeric ID of the region.
region_name Full name of the region.
currency The region’s original currency.
returns Number of returns in the region.
units Number of units sold in the region.
base_revenue Total revenue in the region’s currency.
converted_revenue Total revenue converted into the user’s currency.

Example Response

// GET /reports/sales/regions

{
  "Australia": {
      "region_id": 1,
      "region_name": "Australia",
      "currency": "AUD",
      "returns": 0,
      "units": 108,
      "converted_revenue": "64.87",
      "base_revenue": "65.36"
  },
  "Canada": {
      "region_id": 2,
      "region_name": "Canada",
      "currency": "CAD",
      "returns": 0,
      "units": 32,
      "converted_revenue": "15.94",
      "base_revenue": "16.10"
  },
  ...
}