Subscriptions
Use /reports/subscriptions to get your subscription metrics as JSON or CSV.
Getting Subscriptions Totals
Section titled “Getting Subscriptions Totals”Request
Section titled “Request”GET /reports/subscriptions?start_date={start_date}&end_date={end_date}&products={products}&countries={countries}&granularity={granularity}Arguments
Section titled “Arguments”| 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: product, country, date, and store. |
| products | List | (productId | iap_product_id1, iap_product_id2, …) Product IDs of the in-app purchases (subscriptions) to include in the response. Default: all active subscriptions in your account. Instead of listing each subscription, you can pass the app’s product ID and add include_inapps=true. |
| countries | List | (isoCode | isoCode1;isoCode2;isoCodeN) Countries to limit the report to. Get country codes from /data/countries. Default: all countries. |
| granularity | Granularity | (daily | weekly | monthly | yearly) The date granularity to use when you group by date. Default: daily. |
| format | String | Output format: JSON or CSV. Defaults to JSON. Note: With format=csv, we don’t fully serialize sub-objects (like the product in /subscriptions/products/…), only their reference, to avoid repetition. |
Response
Section titled “Response”| Field | Type | Description |
|---|---|---|
| all_active_subscriptions | Number | The total number of active subscriptions, including free and discounted trials, discounted pay-up-front 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 currently in a 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 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 of subscriptions 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 of subscriptions that weren’t renewed, either directly by the customer or as a result of moving to a different tier or plan. This is an aggregate metric. |
| churn | Number | Cancelled subscriptions as a percentage 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 available for iOS and Mac apps. |
| active_discounted_subscriptions | Number | The number of active subscriptions paying a discounted rate. |
| active_trials | Number | The number of subscriptions currently in a free or discounted trial. |
| 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 cross-grading 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 renewed automatically. |
| 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 now active. |
Example Response
Section titled “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
Section titled “Getting Subscriptions Details”Request
Section titled “Request”GET /reports/subscriptions?group_by={group_by}&start_date={start_date}&end_date={end_date}&products={products}&countries={countries}&format={format}Arguments
Section titled “Arguments”| 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: product, country, date, and store. |
| products | List | (productId | iap_product_id1, iap_product_id2, …) Product IDs of the in-app purchases (subscriptions) to include in the response. Default: all active subscriptions in your account. Instead of listing each subscription, you can pass the app’s product ID and add include_inapps=true. |
| countries | List | (isoCode | isoCode1;isoCode2;isoCodeN) Countries to limit the report to. Get country codes from /data/countries. Default: all countries. |
| granularity | Granularity | (daily | weekly | monthly | yearly) The date granularity to use when you group by date. Default: daily. |
| format | String | Output format: JSON or CSV. Defaults to JSON. Note: With format=csv, we don’t fully serialize sub-objects (like the product in /subscriptions/products/…), only their reference, to avoid repetition. |
Response
Section titled “Response”Like other /reports routes, you can group the response by one value or combine several to get a nested response. The breakdown changes, but the leaves use the same format as the totals object in the previous example.
Example Response Grouped by Day
Section titled “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
Section titled “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 Dates
Section titled “Example Response Grouped by Products and Dates”GET /reports/subscriptions/?group_by=product,date&start_date=-30
{ "2018-11-22": { "5561990123": { "active_subscriptions": 0, "mrr": 0, "churn": 0, ... }, ... }, ...}