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

start_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
(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
One or more pivots separated by a comma (,). Available pivots: product, country, date, and store.


products
(productId | productId1;productId2;productIdN) specific products to include in the response, default: all products in account


countries
(isoCode | isoCode1;isoCode2;isoCodeN) Countries to limit the report to (can be taken from /data/countries, default: include 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 /subscriptions/products/…) the object will not be fully serialized. Only its reference will be.

Response

active_subscriptions The number of paying subscriptions that are active as of the last day of the period.
net_revenue The amount of money generated by subscriptions for the selected period, after the store’s fee.
activations 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 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 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 Subscriptions that have been cancelled as a percent of total active subscriptions. This is a calculated metric.
first_year_subscriptions 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_subscriptions 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 The number of subscriptions that are currently active in free trial.
new_trials The number of new trial subscriptions that have been activated in the selected period.
cancelled_trials The number of trial subscriptions that chose not to convert to a paying subscription.
transitions_in The total number of upgrades, downgrades, and cross-grades that resulted in a subscription activation. This is an aggregate metric.
transitions_out 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 The number of subscriptions that have been cancelled by the customer.
new_subscriptions The number of new subscriptions that were activated by new customers.
trial_conversions The number of subscriptions that have started as a trial and converted to a paying subscription.
reactivations The number of subscriptions that were activated after having expired and not renewed immediately.
renewals The number of subscriptions that automatically renwed successfully.

Example response

// GET /reports/subscriptions?start_date=-30

{
  "active_subscriptions": 1011,
  "active_free_trials": 350,
  "new_subscriptions": 100,
  "cancelled_subscriptions": 10,
  "new_trials": 41,
  "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.00"
}

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

start_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
(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
One or more pivots separated by a comma (,). Available pivots: product, country, date, and store.


products
(productId | productId1;productId2;productIdN) specific products to include in the response, default: all products in account


countries
(isoCode | isoCode1;isoCode2;isoCodeN) Countries to limit the report to (can be taken from /data/countries, default: include 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 /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

{
  "2017-08-22": {
    "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.00"
  },
  ...
}

Example response grouped by country

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

{
  "US": {
    "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.00"
  },
  ...
}

Example response grouped by products and country

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

{
  "2017-08-22": {
    "5561990123": {
      "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.00"
    },
    ...
  },
  ...
}