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 | 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) |
| 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 | 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) |
| 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,
...
},
...
},
...
}