Sales

Important: This version of the API has been deprecated an is no longer supported. v1.1 will be completely deactivated on May 31st, 2015.
The /sales resource provides comprehensive access to sales reports. Reports can be generated in a variety of formats.

Generating a Report By Product, Country, or Date

Request

GET /sales/{type}/{start_date}/{end_date}/?data_source={data_source}&products={product_ids}&country={country}&format={format}

Arguments

type
Type of report to generate. Options: products, dates, countries, products+dates, dates+products, products+countries, countries+products


start_date
(yyyy-MM-dd) Date, inclusive, to start reporting from


end_date
(yyyy-MM-dd) Date, inclusive, to stop reporting


data_source
(daily | weekly | monthly) Whether to use daily or weekly reports. The default data_source is daily. Note: In this version of the API specifying monthly will return results from the financial data source.


products
(productId | productId1;productId2;productIdN) specific products to include in the response


country
(isoCode) Country to limit the report to (can be taken from /data/countries, default: show all countries)


format
Output format: JSON or CSV. Defaults to JSON.

Note: To prevent excessive repetition, when format=csv sub-object (like the product in /sales/products/…) the object will not be fully serialized but only its reference will be.

Response

country Full name of the country when type=countries, null otherwise.
iso Two-letter iso code of the country when type=countries, null otherwise.
product An object representing the product. This will only be populated when type includes products.
downloads An int representing the total number of downloads.
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.
returns An int representing the total number of returns.
gift_redemptions An int representing the number of times products in this reports were gifted.
promos An int representing the total number of promo codes used.

Example Response For Sales By Date Report

// GET /sales/dates/2010-11-24/2010-11-25

{
  "2010-11-24": {
    "country": null,
    "iso": null,
    "product": null,
    "downloads": 39,
    "net_downloads": 38,
    "updates": 6,
    "revenue": "19.02",
    "returns": 1,
    "gift_redemptions": 0,
    "promos": 0
  },
  "2010-11-25": {
    "country": null,
    "iso": null,
    "product": null,
    "downloads": 63,
    "net_downloads": 63,
    "updates": 6,
    "revenue": "37.00",
    "returns": 0,
    "gift_redemptions": 0,
    "promos": 0
  }
}

Example For Sales By Country Report

// GET /sales/countries/2010-05-20/2010-05-25

{
  "United States": {
    "country": "United States",
    "iso": "US",
    "product": null,
    "downloads": 66,
    "net_downloads": 66,
    "updates": 9,
    "revenue": "41.30",
    "returns": 1,
    "gift_redemptions": 0,
    "promos": 0
  },
  "Australia": {
    "country": "Australia",
    "iso": "AU",
    "product": null,
    "downloads": 8,
    "net_downloads": 8,
    "updates": 1,
    "revenue": "4.46",
    "returns": 0,
    "gift_redemptions": 0,
    "promos": 0
  },
  "United Kingdom": {
    "country": "United Kingdom",
    "iso": "GB",
    "product": null,
    "downloads": 4,
    "net_downloads": 4,
    "updates": 0,
    "revenue": "0.57",
    "returns": 0,
    "gift_redemptions": 0,
    "promos": 0
  },
  ...
}

Example For Sales By Product Report

// GET /sales/products/2010-05-20/2010-05-25

{
  "294956": {
    "country": null,
    "iso": null,
    "product": {
      "product_type": "app",
      "name": "Just Run",
      "id": 294956,
      ...
    },
    "downloads": 21,
    "net_downloads": 21,
    "updates": 1,
    "revenue": "0.00",
    "returns": 0,
    "gift_redemptions": 0,
    "promos": 0
  },
...
}

Example For Sales By Product and Date Report

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

// GET /sales/products+dates/2010-05-20/2010-05-25

{
  "294956": {
    "2010-11-24": {
      "country": null,
      "iso": null,
      "product": {
        "product_type": "app",
        "name": "Just Run",
        "id": 294956,
        ...
      },
      "downloads": 11,
      "net_downloads": 11,
      "updates": 0,
      "revenue": "0.00",
      "returns": 0,
      "gift_redemptions": 0,
      "promos": 0
    },
    ...
  },
  "320459": {
    "2010-11-24": {
      "country": null,
      "iso": null,
      "product": {
        "product_type": "app",
        "name": "Looping",
        "id": 320459,
        ...
      },
      "downloads": 28,
      "net_downloads": 29,
      "updates": 6,
      "revenue": "19.02",
      "returns": 1,
      "gift_redemptions": 0,
      "promos": 0
    },
    ...
  }
}

Example For Sales By Date and Product Report

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

// GET /sales/dates+products/2010-05-20/2010-05-25

{
  "2010-11-24": {
    "294956": {
      "country": null,
      "iso": null,
      "product": {
        "product_type": "app",
        "name": "Just Run",
        "id": 294956,
        ...
      },
      "downloads": 11,
      "net_downloads": 11,
      "updates": 0,
      "revenue": "0.00",
      "returns": 0,
      "gift_redemptions": 0,
      "promos": 0
    },
    ...
  },
  "2010-11-25": {
    "294956": {
      "country": null,
      "iso": null,
      "product": {
        "product_type": "app",
        "name": "Just Run",
        "id": 294956,
        ...
      },
      "downloads": 10,
      "net_downloads": 10,
      "updates": 1,
      "revenue": "0.00",
      "returns": 0,
      "gift_redemptions": 0,
      "promos": 0
    },
    ...
  },
  ...
}

Getting “All Time” totals by Product or Country

A very common use case is to get all the data for an app and add it up for an “All time total”. Instead of having you do all that work on the client side, the API has a special exception just for that: simple omit the start and end dates from any non-dates related sales resource.

Request

GET /sales/{type}/?data_source={dataSource}&products={productIds}&country={country}

Where type is one of the following: products, products+countries, countries, countries+products. All other attributes are the same as for the other /sales calls above.

Example For All Time Totals By Product

// GET /sales/dates+products/2010-05-20/2010-05-25

{
  {
  "300000": {
    "downloads": 1658635,
    "updates": 10154038,
    "returns": 0,
    "net_downloads": 1658635,
    "promos": 0,
    "revenue": "0.00",
    "gift_redemptions": 0,
    "product": {
      "id": 300000,
      "ref_no": "294056041",
      "store_id": 0,
      "store_name": "apple",
      "added_timestamp": "2009-01-02T17:50:00",
      "name": "Freedom Runs",
      "icon": "http://a2.phobos.apple.com/us/r1000/030/Purple/75/f4/1a/mzl.yxfymshua.175x175-75.jpg",
      "active": true,
      "hidden": false,
      "sku": "01",
      "in_apps": [],
      "product_type": "app",
      "addons": []
    }
  },
  ...
}

For some products, such as free apps from the Android Market, this resource will give complete “all time” data set, and not just for the data that’s been imported into the Appfigures account.

Generating a By Region Sales Report

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

Request

GET /sales/regions/{startDate}/{endDate}?products={productIds}

Arguments

startDate
(yyyy-MM-dd) Date, inclusive, to start reporting from
endDate
(yyyy-MM-dd) Date, inclusive, to stop reporting
productIds (optional)
(productId | productId1;productId2;productIdN) specific products to include in the response
format new (optional)
Output format: json or csv. Defaults to json.

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 /sales/regions/2010-10-25/2010-11-25?products=12435

{
  "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"
  },
  ...
}
  • nick

    Does this require a manual ‘sync’ to get the latest data?

    • st

      Looks like it.

      • nick

        This sort of contradicts the whole “access is available to all members, regardless of plan type”.

        • appfigures

          All plans may access the API to get data from their account. In the free plan data only comes in when a manual sync occurs which is why you won’t see data in the API until you sync.

  • http://twitter.com/JulienCoquet Julien Coquet

    Any chance we could get a sort parameter in there? Thanks! 🙂

    • appfigures

      The sales route always returns a dictionary which is not possible to sort 😉

  • Vasiliy Fedorov

    A response has ‘revenue’ but not ‘total_revenue’. Please correct docs.

    • appfigures

      Updated. Thanks!