Subscriptions | App Store API

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

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

Getting subscriptions totals

Request

GET /reports/subscriptions?start_date={start_date}&end_date={end_date}&products={products}&countries={countries}&granularity={granularity}

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: product, country, date, and store.
products	List	(productId \| iap_product_id1, iap_product_id2, …) A list of product_ids of in-app purchases (subscriptions) product_ids to include in the response. Default: all active subscriptions in account. Important: You can submit the product_id of the app and append `include_inapps=true` instead of specifying individual subscriptions.
countries	List	(isoCode \| isoCode1;isoCode2;isoCodeN) Countries to limit the report to (can be taken from /data/countries, default: include all countries)
granularity	Granularity	(daily \| weekly \| monthly \| yearly) which date granularity to use when grouping-by date. default: daily)
format	String	Output format: JSON or CSV. Defaults to JSON. Note: To prevent excessive repetition, when `format=csv`, sub-object (like the product in /subscriptions/products/…) the object will not be fully serialized. Only its reference will be.

Response

Field	Type	Description
all_active_subscriptions	Number	The total number of active subscriptions including free and discounted trials, discounted pay upfront and pay as you go subscriptions, and standard subscriptions.
active_subscriptions	Number	The number of active subscriptions that are paying the standard subscription price.
active_free_trials	Number	The number of subscriptions that are currently active in free trial.
paying_subscriptions	Number	The number of active subscriptions that are paying the standard subscription price or a discounted rate.
actual_revenue	Money	The amount of money generated by subscriptions for the selected period, after the store’s fee.
mrr	Money	The amount of revenue subscriptions are earning in a month. MRR includes revenue generated from monthly subscriptions, as well as well as the monthly portion of longer term subscriptions.
gross_mrr	Money	The amount of revenue subscriptions are earning in a month before the store takes its fee.
gross_revenue	Money	The amount of money generated by subscriptions for the selected period, before the store’s fee.
activations	Number	The number subscriptions that have been activated in the period, including: activations from new subscriptions, re-activations, trials converting to paying subscriptions, and tier/plan changes. This is an aggregate metric.
cancellations	Number	The number subscriptions that were not renewed directly by the customer, or as a result of moving to a different tier or plan. This is an aggregate metric.
churn	Number	Subscriptions that have been cancelled as a percent of total active subscriptions. This is a calculated metric.
first_year_subscribers	Number	The number of subscriptions that have been active for less than a year. Stores deduct a higher fee for these subscriptions. This metric is only available for iOS and Mac apps.
non_first_year_subscribers	Number	The number of subscriptions that have been active for more than a year. Stores deduct a lower fee for these subscriptions. This is a calculated metric, and is only availabel for iOS and Mac apps.
active_discounted_subscriptions	Number	The number of active subscriptions that paying a discounted rate.
active_trials	Number	The number of subscriptions that are currently active in free trial and discounted.
new_trials	Number	The number of new trial subscriptions that have been activated in the selected period.
cancelled_trials	Number	The number of trial subscriptions that chose not to convert to a paying subscription.
transitions_in	Number	The total number of upgrades, downgrades, and cross-grades that resulted in a subscription activation. This is an aggregate metric.
transitions_out	Number	The total number of subscriptions that have been cancelled as a result of the customer upgrading, downgrading, or crossgrading to a different subscription tier/plan. This is an aggregate metric.
cancelled_subscriptions	Number	The number of subscriptions that have been cancelled by the customer.
new_subscriptions	Number	The number of new subscriptions that were activated by new customers.
trial_conversions	Number	The number of subscriptions that have started as a trial and converted to a paying subscription.
reactivations	Number	The number of subscriptions that were activated after having expired and not renewed immediately.
renewals	Number	The number of subscriptions that automatically renwed successfully.
active_grace	Number	The total number of subscribers that could not be charged and are being retried automatically.
new_grace	Number	The number of new subscribers that could not be charged and are being retried automatically.
grace_drop_off	Number	The number of subscriptions that have been cancelled because they could not be charged.
grace_recovery	Number	The number of subscriptions that were charged successfully after failing and are now active.
new_trial_grace	Number	The number of new trial subscriptions that upgraded to a paid subscription but couldn’t be charged.
trial_grace_drop_off	Number	The number of trial subscriptions that were cancelled because they couldn’t be charged.
trial_grace_recovery	Number	The number of trial subscriptions that were charged successfully after failing and are not active.

Example response

GET /reports/subscriptions?start_date=-30

{
    "active_subscriptions": 0,
    "active_free_trials": 0,
    "new_subscriptions": 0,
    "cancelled_subscriptions": 0,
    "new_trials": 0,
    "trial_conversion_rate": "0.00",
    "mrr": "0.00",
    "actual_revenue": "0.00",
    "renewals": 0,
    "first_year_subscribers": 0,
    "non_first_year_subscribers": 0,
    "reactivations": 0,
    "transitions_out": 0,
    "trial_cancellations": 0,
    "transitions_in": 0,
    "activations": 0,
    "cancellations": 0,
    "trial_conversions": 0,
    "churn": "0.0000",
    "gross_revenue": "0.00",
    "gross_mrr": "0.00",
    "active_grace": 0,
    "new_grace": 0,
    "grace_drop_off": 0,
    "grace_recovery": 0,
    "new_trial_grace": 0,
    "trial_grace_drop_off": 0,
    "trial_grace_recovery": 0
}

Getting subscriptions details

Request

GET /reports/subscriptions?group_by={group_by}&start_date={start_date}&end_date={end_date}&products={products}&countries={countries}&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: product, country, date, and store.
products	List	(productId \| iap_product_id1, iap_product_id2, …) A list of product_ids of in-app purchases (subscriptions) product_ids to include in the response. Default: all active subscriptions in account. Important: You can submit the product_id of the app and append `include_inapps=true` instead of specifying individual subscriptions.
countries	List	(isoCode \| isoCode1;isoCode2;isoCodeN) Countries to limit the report to (can be taken from /data/countries, default: include all countries)
granularity	Granularity	(daily \| weekly \| monthly \| yearly) which date granularity to use when grouping-by date. default: daily)
format	String	Output format: JSON or CSV. Defaults to JSON. Note: To prevent excessive repetition, when `format=csv`, sub-object (like the product in /subscriptions/products/…) the object will not be fully serialized. Only its reference will be.

Response

Just like other routes in the /reports family, the response can be grouped by a variety of values either one at a time or combined to produce a nested response. While the breakdown may change, the leaves of the response follow the same format as the totals object from the previous example.

Example response grouped by day

GET /reports/subscriptions/?group_by=dates&start_date=-30

{
  "2018-11-22": {
    "active_subscriptions": 0,
    "mrr": 0,
    "churn": 0,
  },
  ...
}

Example response grouped by country

GET /reports/subscriptions/?group_by=country&start_date=-30

{
  "US": {
    "active_subscriptions": 0,
    "mrr": 0,
    "churn": 0,
        ...
  },
  ...
}

Example response grouped by products and country

GET /reports/subscriptions/?group_by=product,date&start_date=-30

{
  "2018-11-22": {
    "5561990123": {
      "active_subscriptions": 0,
      "mrr": 0,
      "churn": 0,
      ...
    },
    ...
  },
  ...
}