Subscriptions

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}

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)
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
active_subscriptions Number The number of paying subscriptions that are active as of the last day of the period.
actual_revenue Money The amount of money generated by subscriptions for the selected period, after 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.
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. This is a calculated metric that is currently only available for iOS and Mac apps.
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_trials Number The number of subscriptions that are currently active in free 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 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)
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,
      ...
    },
    ...
  },
  ...
}