Overview

Plan Availability

This feature is only available to customers on the Professional and/or Elite subscription plan. To request to upgrade to this plan, please reach out to your Recurly account manager or [email protected] for more 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

Key Details

How it works

Recurly uses a combination of event notifications sent by the App Stores, REST API calls to App Store platforms, and report downloads 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

In order for Recurly to receive all the information necessary to provide you a complete picture of your Apple app subscriptions, you will need to forward the Apple App Store server notifications to Recurly, and allow Recurly to pull additional subscription and report information via an API key. The following steps will guide you through the configuration within Apple, and within Recurly for the app store connection.

1. Log into Apple App Store Connect via this link and click Keys within “Users and Access”. This is where you will create a specific API key for the Recurly connection.
   1. In order to complete the required steps in these instructions, you will need appropriate access (e.g., “App Manager” and “Sales”) within Apple App Store Connect. If you run into access issues, please reach out to one of your Apple App Store Connect Admins.
2. Create an API key by clicking the + (plus) symbol near “Active”
   1. Input a name to uniquely identify the key
   2. For Access, select both Developer, and Sales and Reports (see example)
      1. 
   3. Click "Generate" to generate the API key
3. Once the key is generated, you will see an option to download the key from the table of Active keys. Please download that private key file (.p8 file), and save it in a secure location. You will only be able to download that file once, so be careful to securely store it.
4. For that key, save the “Key ID”, which is found in the same row of information for the key you just created.
5. In addition, save the “Issuer ID”, which is found just above the list of Active keys.
6. While in Apple App Store Connect, navigate to “Reports”, which is found near the top center of your page. It can also be found from the App Store Connect page, by clicking on “Payments and Financial Reports”.
7. When viewing the Reports page, save your “Vendor #”, which is listed on the top left of the page.
8. You now have all the information from Apple that you need to connect Recurly.
9. In Recurly, navigate to App Management -> App Connector, and click on “Add Source” under “Apple App Store”.
   1. If you are only replacing the API key, click "View Details" next to "Apple App Store".
10. This is where you will input all the information you noted earlier regarding the API key.
    1. For “Authentication Key”, open the private key p8 file you downloaded in a text editor, and paste the entire contents in the field.
    2. If you have already enabled the connection, and are coming back to replace the API key, you only need to replace the "Authentication Key" and "Key ID" fields. Once those are edited, the new API key is being used, and you can skip the remaining configuration skips listed below.
11. As shown in the example below, ensure you have all 4 fields populated. Your input should look similar to what is shown. Once all 4 fields look good, click “Enable connection”.
    1. 
12. Once enabled, you now need to point the Apple App Store notifications to Recurly. While on that same page in Recurly, copy the “Production URL” shown to your clipboard.
13. Back in Apple App Store Connect, navigate to your app. You can get to your app in “My Apps”, or from Apps on the top of your page.
14. While viewing your App in Apple App Store Connect, navigate to the “App Store Server Notifications” section under General -> App Information.
15. Next to “Production Server URL”, click Edit, and input the copied URL from Recurly into the “Production Server URL” field. In that window, ensure “Version 2 Notifications” are selected, and then click Save.
    1. If you are testing and using a non-Production site, you will want to edit the “Sandbox Server URL” instead of Production.
16. Once the server URL for your Apple app is correctly pointing to Recurly, go back to your open page within Recurly and check the box to confirm that you have added the URL.
17. Click “Complete Configuration”
18. You have now completed the steps necessary to connect Recurly with your Apple app.

Google Play

1. Before connecting your Google Play app to Recurly, ensure you have completed the following prerequisite steps
   1. You have set up a Google Play Developer account (instructions here)
   2. You have set up a profile in Google Payments Center, and linked that profile to your developer account (instructions here)
      1. If your app is not yet live, you can skip this step and come back to it before going live.
2. Following these Google instructions, configure access to the Google Play Developer API through the Google Cloud Console and Google Play Console. When done following those instructions, you should have completed the following tasks. Please note that we have provided additional info below to the linked Google instructions.
   1. Link your developer account to a new or existing Google Cloud Project.
   2. Enable the Google Play Developer API for your linked Google Cloud Project.
   3. Set up a service account with appropriate Google Play Console permissions to access the Google Play Developer API
      1. When you are creating the service account, make sure to add the “Pub/Sub Admin” and “Monitoring Viewer” roles, which give the service account necessary permissions to the Google Project.
      2. Copy the e-mail address for the new service account to your clipboard.
   4. Provide the service account you created with access to your app within Google Play Console
      1. Within Google Play Console, click “Invite new users” from the “Users and Permissions” page.
      2. Within Permissions, click “Add app” and select your app from the list. When prompted to select permissions, ensure that you select (add) both “View financial data, orders, and cancellation survey responses” and “Manage orders and subscriptions”.
3. Following these Google instructions, create a new JSON key for your service account
   1. Given that you can never recover the private JSON key from Google, be sure to securely store the key. You will need this key for an upcoming step within Recurly.
4. Referring to the section entitled “Find your Google Cloud Storage URI” of these Google instructions, save a link to the Google Storage URI that points to the Earnings report.
5. With the above information, connect your Google app to Recurly
   1. In Recurly, navigate to App Management -> App Connector, and click Add Source for Google Play Store.
   2. Using the example shown below, input your service account JSON key and Earnings report URI.
      1. 
   3. Click “Enable Connection”
   4. Once enabled, a Production URL for App Management is created. Leave this page open, and continue to the next step.
6. Follow these steps to set up Google Pub/Sub, which is used by Recurly to receive notifications from Google regarding subscription activity.
   1. Following these Google instructions, create a topic. As shown in the example below, uncheck “Add a default subscription” (we will create one in the next step).
      1. 
   2. While viewing the topic, save the “Topic name” since you will need it later. This topic name is the longer URI version (e.g., projects/{project_id}/topics/{topic_name}), and not just the name you provided when creating the topic.
   3. Add a subscription to that topic by clicking “Create Subscription” within the topic, and inputting the following information:
      1. Referencing the example below, select “Delivery type” of Push and paste the URL from Recurly App Management into “Endpoint URL”
         1. 
      2. Referencing the example below, change Acknowledgement deadline from the default to 60 seconds
         1. 
      3. Referencing the example below, change Retry policy to “Retry after exponential backoff delay”, with the default of 10 seconds for minimum backoff, and 600 seconds for maximum backoff.
         1. 
      4. Click Create to create the subscription
   4. Following these Google instructions, grant Google Play privileges to publish notifications to your topic. You can see an example of this step below.
      1. 
7. Following these Google instructions, enable real-time notifications for your app by inputting the topic name and sending a test message.
   1. This is where you will use the longer URI version of your topic that you saved in a previous step.
8. Once you have completed setting up Google Pub/Sub and real-time notifications for your Google app, proceed back to Recurly. Check the checkbox that confirms you have completed setting up the Google configuration, and then click Complete Configuration.
9. App Management within Recurly is now set up. You can now look forward to viewing your Google Play app information within Recurly! Please note that you have to wait at least 36 hours before the appropriate Google access you configured is pushed through their systems.

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

'Subscription-External' and 'Invoice-External' exports are available that provide details on all of the External Subscriptions and External Invoices sync’d into Recurly on your behalf. These exports can be accessed either manually or through our Automated Export system.