Overview

App management gives you a complete picture of your subscription business by combining analytics across app stores with web through a simple, automated data sync. In addition, app management streamlines your processes for cross-platform entitlements checking and centralizes all of your cross platform subscription lifecycle notifications.

Plan Availability and Cost

App management is available to customers on the Recurly Professional or Elite plans for an additional cost. Please reach out to your Recurly account manager or support for more pricing details.

Key Benefits

Grow subscription revenue by uncovering new subscription acquisition and retention insights and opportunities through cross-platform analytics

Enhance the subscriber experience by gaining a holistic, cross-platform view of subscribers and building an optimal communication and engagement strategy

Increase operational efficiencies by developing new cross-platform subscription processes and workflows through robust APIs and webhooks

Save development time and resources by eliminating the need to build and maintain app store data integrations, saving scarce resources across web and mobile engineering teams

Detailed Description

How it works

Recurly uses a combination of event notifications sent by the App Stores, REST API calls to App Store platforms, report downloads and, in some cases, a Software Development Kit (SDK) that can be integrated into your client applications to obtain the most up to date information about your App Store customers, subscriptions, and revenue.

📘

Note: One-time purchases created in the App Stores are not currently tracked / supported.

Data that is ingested from the App Store is stored within and accessible from Recurly via External Subscriptions and Accounts. See below for more information on each:

External Subscriptions

App Store subscriptions are reflected in Recurly through the External Subscription object. External Subscriptions are not subject to any of the subscription management functionality that Recurly provides for standard Recurly Subscriptions. The primary purpose is to reflect the state of subscriptions managed by platforms outside of Recurly (ie. the App Stores). App Store initiated modifications to External Subscriptions, including state changes, are updated by Recurly and will be reflected in Data Exports, and Recurly API.

External Subscriptions contain several key fields that represent the corresponding App Store Subscription:

External ID
The id of the subscription as generated by the source App Store

External Product Reference Code
Associates the subscription with a product (ie. plan) in your App Store product catalog. This code can also be used to associate the subscription and App Store product with an External Product configured within Recurly.

External Connection Type
Identifies the source App Store (e.g. Apple, Google) from which the External Subscription originated.

App Identifier
Identifies the specific application provided by a given App Store account which generated the External Subscription

Last Purchased
The date and time of the most recent payment event (e.g. renewal, initial purchase) related to the External Subscription.

Quantity
The number of subscriptions purchased

Activation Date
The date and time when the External Subscription was first created / purchased in the source App Store

Expiration Date
The date and time when the External Subscription will expire in the source App Store

Auto Renew
Indicates whether or not the External Subscription will auto-renew when it reaches the expiration date.

State
The current state of the External Subscription which can be any of the following:

• Active
  The subscription is past the activation date, hasn't expired, and is set to auto-renew at the expiration date
• Future
  The subscription hasn't reached the activation date or expiration date
• Canceled
  The subscription is past the activation date, hasn't expired, and is not set to auto-renew at the expiration date
• Expired
  The subscription has reached the expiration date.

Accounts

External Subscriptions are associated with standard Recurly Accounts, which are used to represent customer data. An Account can be associated with one or more External Subscriptions and / or standard Recurly Subscriptions. If a Recurly Account has an external subscription linked to it, it will show up under the External Accounts tab in the Recurly Accounts UI.

Historical App Store Data Imports

Due to limitations with the App Store platforms, Recurly is not able to automatically ingest historical data from the App Stores on your behalf. This includes any App Store subscriptions that were created prior to your use of Recurly app management. In order to reflect this data in Recurly, it is necessary to backfill our records with subscription and customer information stored on your side. Refer to this section of the documentation for the key fields that will need to be provided in order to complete the import process. Please contact our support team who will be able to facilitate the historical import.

What you get

Consolidated Data Analysis and Insights

Analytics dashboards are available in order to provide you with insights and a side by side comparison of your business performance across the App Stores. Additionally, you are able to extract your App Store data from Recurly for further transformation and analysis by leveraging the Data Exports or the REST APIs. Metrics are grouped in three major categories including Subscriptions, Revenue, and Customers. See below for more information:

Subscriptions

External Subscription Totals - Shows total count of active external subscriptions by activation date.

External Subscription Growth - Shows total count of subscriptions grouped by state (e.g. active, canceled, expired) along with the net number of subscriptions (actives minus churned) for a given time period.

External Subscriptions by Product - Total number of active subscriptions delineated by the external product to which they're associated.

Subscriber Retention

Uses cohort analysis to evaluate paid subscriber retention and churn rates over a specified timeframe for each group, based on sign-up month. The sign-up month is the month in which the customer has their first activated external subscription.

Billings

The Billings dashboard total gross revenue processed in the App Stores over a selected time period. Billings can be broken down by the App Store from which they originated, and by new revenue (successful first time payments on an Account) and renewing revenue (successful renewed payments on an Account). Billings can be viewed by the transacted currency, or converted to your Recurly site configured currency (default view)

📘

The app store related dashboards and metrics are currently separated from the standard set of Recurly analytics dashboards in a section called External Sources.

Customer Entitlement Checks

Entitlements can be checked in one of two ways: 1.) Usage of the External Subscription endpoints or 2.) Usage of the the Entitlements feature and associated REST API endpoints.

Business Process Automation

It may be desirable to trigger various business processes based on App Store subscription lifecycle events. Recurly can be used as a hub for identifying and taking action on these events using the webhooks and REST API.

How to Implement

Apple App Store

Server-side notifications & REST API Calls

Recurly relies on the server-side notifications sent by the App Stores in order to obtain data related to new subscriptions and customers, as well as any updates that occur throughout the subscription lifecycle. In some cases, Recurly initiates REST API calls to the App Stores to augment data received in the notifications.

In order to receive these notifications on your behalf, Recurly provides a you with a unique URL for each App Store when you complete the configuration steps in Recurly UI.

These notification URLs must be individually configured in your Apple App Store as follows:

1. Sign in to App Store Connect and select any apps that you would like to configure.
2. Navigate to the App Information section
3. Paste the URL you got from Recurly app management into the "Production Server URL" field.
4. Click "Save" at the top of the page.

Revenue Report Extraction

Additional revenue data that can't be obtained through the App Store server-side notifications or REST API calls is extracted via App Store reports. In order for Recurly to access these reports additional credentials will need to be provided as follows for Apple App Store:

The following information must be taken from Apple App Store and added to your Recurly app management configuration:

• Issuer ID (ie. apple_issuer_id)
  Found in: App Store Connect > Users and Access > App Store Connect API > Issuer ID
• App Store Connect API Key
  A private key (.p8 file) that can be generated in the App Store Connect console. Once you have generated the key you can download it using the provided call to action. Note: When generating the key, generate a key with Sales and Reports permissions
• Key ID (ie. apple_key_id)
  Found in: App Store Connect > Users and Access > App Store Connect > Key ID
• Apple Vendor Number (ie. apple_vendor_number)
  Found in: App Store Connect on the homepage, then click Payments and Financial Reports

Client SDK Integration

In order to obtain your Apple App Store revenue data (e.g. transaction price, currency, etc.), it is necessary to integrate Recurly's client SDK into the app used by your end customers.

A Swift based SDK is provided for iOS in order to facilitate subscription purchases on the Apple App Store. This SDK is required in order for Recurly to obtain price and currency information related to subscription purchases in the Apple App Store and is used as the basis for the revenue metrics.

Google Play

Server-side notifications & REST API Calls

Recurly relies on the server-side notifications sent by the App Stores in order to obtain data related to new subscriptions and customers, as well as any updates that occur throughout the subscription lifecycle. In some cases, Recurly initiates REST API calls to the App Stores to augment data received in the notifications.

In order to receive these notifications on your behalf, Recurly provides a you with a unique URL for each App Store when you complete the configuration steps in Recurly UI.

These notification URLs must be individually configured in your Google Play store as follows:

1. Make sure you've completed all of the steps as described in the Android Developer documentation, Google Play's Billing System "Getting Ready". See below more detail:
   1. Complete all of the steps described in Publish and receive messages in Pub/Sub by using the console. Make sure to create a subscription of push delivery type and enter the Recurly app management URL (noted above) into the "Endpoint URL" field
   2. Grant permissions so Google Play can publish notifications to the topic.
   3. Configure Google Play Console for an existing app.
2. Enable usage of the Google Play Developer API
   1. Link your account and project
   2. Enable the API using the Service Account approach

You will also need to enter the Service Account key (JSON format) for your Google Service Account into the Recurly UI configuration screen.

Revenue Report Extraction

Additional revenue data that can't be obtained through the App Store server-side notifications or REST API calls is extracted via App Store reports. In order for Recurly to access these reports additional credentials will need to be provided as follows for Goolge Play store:

The following information must be taken from the Google Play console and added to your Recurly app management configuration:

• Google Cloud Storage URI. See here for more information.
• NOTE: Recurly only needs access to the Earnings report so the URI to include in Recurly should be the URI that points to the Earnings report. In addition, ensure the Service Account created in the steps above has permissions to access the Earnings report.

External Product Catalog

Recurly UI provides an interface to manage a multi-platform product catalog that can be used to reflect the recurring products (ie. Plans) as they exist in the App Stores and link them to a corresponding Recurly Plan. This catalog will be used as the basis for matching App store subscription purchases to specific recurring product catalog items in Recurly.

Creating External Products

External Products include fields for you to input the identifiers of any corresponding plans / products that you have configured in the App Stores. When subscriptions are ingested from the App Stores, Recurly looks up the related External Product using the the App Store identifier. To create an External Product, follow these steps:

1. Navigate to External Connections > External Products in the left had nav of the Recurly Admin UI.
2. Click the New External Product button.
3. Give the external product a name (e.g. Monthly Gold Plan).
4. Select the Recurly plan you want to map to this external product (e.g. Monthly Gold Plan - Web).
5. Click the Add Source button (here you will map Apple and Goolge products to this external product).
6. For Apple App Store, include the Apple product id of the product you want to map to this external product.
7. For Google Play, include both the product id and base plan id you want to map to this extneral product. Seperate the product id and base plan id with a '+'. For example, 33000+33000-1 where 33000 is the product id and 33000-1 represents the base plan id.
8. Click Create External Product to save your changes.

It is not possible to create and manage External Products via the Recurly API at this time.

Unassigned Purchases

In cases where Recurly ingests App Store subscriptions (i.e. External Subscriptions) that you have not associated with an External Product, they will be stored and designated as an Unassigned Purchase. A Recurly UI workflow is provided for you to "resolve" these flagged purchases by assigning them to a new or existing External Product based on the App Store product identifier that exists on the subscription. The Entitlements feature and some of the provided analytics metrics (e.g. External Subscriptions by Product) require subscriptions to be assigned to External Products in order to function.

Entitlements

The Entitlements feature enables you to create / configure granular features and functionality (Ex. Unlimited Logo Creation) that are unlocked through subscription purchases in the App Stores. Each Entitlement can be created with a unique Code, that can be referenced in your application and used as the basis for authorizing the customer to access the associated feature.

Entitlements can be assigned / associated with one or more External Products. The Entitlements endpoint in the REST API is used to check if a particular customer Account has access to a given Entitlement based on purchases of subscriptions based on the underlying External Product.

Sync Process & Integration Guide

Recurly primarily uses App Store server-side notifications and REST API calls in order to drive the creation of, and updates to, the Recurly External Subscriptions and Recurly Accounts that represent App Store subscriptions and customer data. The following describes the standard sequencing of events that occur once you've configured your App Store credentials within Recurly:

New Subscriptions

1. A new customer purchases an App Store subscription using your client application. Note: your application code must generate and pass a unique identifier for the customer to the App Stores when the purchase is made. See here for more information regarding Apple App Store and here for Google Play.
2. Recurly will receive a notification (from the App Store platform) informing of the new subscription along with the associated customer identifier that you passed in Step 1. Recurly will make additional REST API calls as needed to obtain the any additional data required.
3. Recurly will find (using the Recurly External Account Code) or create an Account using the identifier obtained in Step 2, create an External Subscription, and associate it with the Account.
4. A Recurly webhook will be sent to any webhook endpoints that you've configured informing of the new External Subscription

❗️

In order for Recurly to create External Subscriptions and associate them to a Recurly Account, it is required that you record a unique identifier for the end customer and associate them with the purchase at time of creation (see Step 1 of the flow)

Subscription renewals and updates

1. Recurly will receive notifications from the App Stores regarding various subscription changes and update its records to reflect the new information
2. A Recurly webhook will be sent to inform you of the update and the lifecycle event that triggered it. A list of lifecycle webhooks can be found here.

🚧

Recurly will not ingest any App Store subscription renewals or modifications if it did not receive an App Store notification of the initial subscription creation or if the subscription was not imported as part of the historical import process.

Developer Interfaces

Recurly REST API (v2 and v3)

A set of REST API endpoints are provided to enable extraction of App Store subscription data using the Recurly platform.

External Products

These endpoints are used to view the details related to the External Products that have been configured via the Recurly UI

• List all External Products by Site: API v3 and API v2
• Fetch an External Product: API v3 and API v2

External Subscriptions

These endpoints are used to pull details about the External Subscription. The following links provide additional information about the External Subscription attributes that are returned for each endpoint.

• List all External Subscriptions by Site: API v3 and API v2
• List all External Subscriptions by Account: API v3 and API v2
• Fetch an External Subscription: API v3 and API v2

Entitlements

• List Entitlements granted to an Account: API v3 and API v2

Webhooks

A set of webhook notifications are provided that represent the various updates to App Store subscriptions that occur during the subscription lifecycle. For a complete list of the App Store notification types and corresponding Recurly webhook events, please refer to the Appendix, section titled “App Store / Recurly Lifecycle Notifications”

Note that the Recurly webhook payloads are “lightweight” in nature and will require a subsequent call to the REST API in order to obtain the most up to date information about the App Store subscriptions. In the case of the examples below, which show both XML and JSON representations of webhooks informing of a new External Subscription, the Fetch an External Subscription endpoint would be called with the value of the “id” field provided in the webhook payload.

{
  "id": "s0lo0hdfmauc",
  "object_type": "external_subscription",
  "site_id": "qpem7fkwr763",
  "event_type": "created",
  "event_time": "2022-12-06T22:19:15Z"
}

<new_external_subscription_notification>
  <external_subscription>
    <id>uuid</>
  </external_subscription>
  <external_resource>
    <id></id>
    <external_object_reference></external_object_reference>
  </external_resource>
  <external_product_reference>
    <id></id>
    <reference_code></reference_code>
    <created_at></created_at>
    <updated_at></updated_at>
  </external_product_reference>
</new_external_subscription_notification>

The following table provides a catalog of the Recurly external subscription webhook event types and the corresponding Apple App Store and Google Play notifications.

Data Exports

An export is available that provides details on all of the External Subscriptions sync’d into Recurly on your behalf. This export can be accessed either manually or through our Automated Export system.