Connect your Apple App Store and Google Play apps to Recurly App Management to track subscription lifecycles, then configure external products, entitlements, and webhooks.
To give you a complete view of your app subscription lifecycles and their revenue, Recurly needs two things: the real-time notifications from Apple and Google, and API access to retrieve key subscription info. This one-time setup connects your mobile apps to Recurly. Work through the platform you use — Apple, Google, or both — then finish with external products, entitlements, and webhooks.
Before you beginRead through the App Management key details before connecting Apple or Google. You may need to make slight modifications to the subscription purchasing workflow in your mobile apps.
Connect your mobile apps
Choose your platform below. If you offer subscriptions on both, complete each tab.
Prerequisites
Before configuring Recurly App Management, create a new Apple App Store Connect API key with the right permissions. You'll need to be an Account Holder or Admin in Apple App Store Connect to complete these steps — if you hit permission issues, reach out to one of your Apple App Store Connect Admins.
1
Log into App Store Connect
Log into Apple App Store Connect. You'll be creating an App Store Connect API key — not an In-App Purchase key — for the Recurly connection.
2
Create an API key
Select the + (plus) symbol near "Active." Enter a name to uniquely identify the key, and for Access select both Developer and Sales and Reports. Then select Generate.
3
Download and store the private key
From the table of Active keys, download the private key file (.p8) and save it in a secure location. You can only download this file once, so store it carefully.
4
Save the Key ID
Find and save the Key ID in the same row as the key you just created.
5
Save the Issuer ID
Find and save the Issuer ID just above the list of Active keys.
6
Open Reports
Navigate to Reports, near the top center of the page. You can also reach it from the App Store Connect page by selecting Payments and Financial Reports.
7
Save your Vendor #
On the Reports page, save your Vendor #, listed at the top left. You now have everything from Apple you need to connect Recurly — stay logged in for one more Apple step below.
Configuration
1
Add the Apple source in Recurly
Navigate to App Management → App Connector. Under Apple App Store, select Add Source. If you're only replacing the API key, select View Details next to Apple App Store instead.
2
Input your key information
Enter the details you noted earlier. For Authentication Key, open the .p8 private key file in a text editor and paste the entire contents — including the hyphens and the BEGIN PRIVATE KEY and END PRIVATE KEY lines.
Replacing an existing keyIf you've already enabled the connection and are back to replace the API key, you only need to update the Authentication Key and Key ID fields. Once those are edited, the new key is in use and you can skip the remaining configuration steps.
3
Enable the connection
Ensure all four fields are populated and look similar to the example, then select Enable connection.
4
Copy the Production URL
Copy the Production URL shown on that page to your clipboard — you'll point Apple's notifications to it next.
Revenue-only setupIf you're only configuring App Management to push mobile app earnings into Recurly RevRec, you can stop here. Note that skipping the remaining steps means App Management won't provide visibility into your subscription lifecycles and related events.
5
Open your app in App Store Connect
Back in Apple App Store Connect, navigate to your app via My Apps, or from Apps at the top of the page.
6
Find App Store Server Notifications
In your app, go to App Store Server Notifications under General → App Information.
7
Set the Production Server URL
Next to Production Server URL, select Edit and paste the copied Recurly URL. Ensure Version 2 Notifications is selected, then select Save. If you're testing on a non-Production site, edit the Sandbox Server URL instead.
8
Confirm the URL in Recurly
Return to the open Recurly page and check the box confirming you've added the URL.
9
Complete configuration
Select Complete Configuration. Your Apple app is now connected to Recurly.
NoteThe "Last Notification Received" date stays blank until Recurly receives a valid notification from Apple. Test notifications sent directly from Apple App Store Connect won't affect this date.
Configure App Management
Once your mobile apps are connected, complete the configuration below.
Creating external products
External products let Recurly associate your unique Apple and Google subscriptions with a single product in Recurly — so you can track one subscription type whether it's sold on the web or your mobile apps. You only need to do this once per subscription you've created in Apple or Google.
1
Open External Products
Navigate to App Management → External Products in the left-hand navigation.
2
Create a new external product
Select New External Product.
3
Name it
Give the external product a name, such as Monthly Gold Plan.
4
Map a Recurly plan
Select the Recurly plan you want to map to this external product, such as Monthly Gold Plan - Web.
5
Add your source and reference code
Select Add Source to map your Apple or Google product, then enter the External Reference Code (details below).
Apple: provide the Apple Product ID of the product you want to map. You'll find it when viewing the details of a specific subscription in Apple App Store Connect.
Google Play: a subscription can have one or more plans, so you need both the Product ID and Base Plan ID. For example, with a Product ID of "ACME" and a Base Plan ID of "Monthly_Pass," you'd enter ACME+Monthly_Pass as the External Reference Code. In Google Play Console, go to Monetize → Products → Subscriptions; the Product ID is on the subscription's details view, and the Base Plan ID is in the first column of the "Base plans and offers" table.
6
Repeat for the other store
If you offer the same subscription via the other app store, repeat the previous step.
7
Save
Select Create External Product to save your changes.
For each subscription offered via Apple or Google, you should end up with one external product in Recurly. For example, if you offer a monthly and a yearly subscription, you'll have two external products when done. The example below shows three subscription offerings identified as external products.
Entitlements
Entitlements give you an easy way to control and grant access to features within your mobile app. When you create an entitlement, you'll see an option to assign an external product — that's how you connect one of the external products you just created. For full details, see the entitlements feature docs.
If you plan to use entitlements, navigate to Configuration → Entitlements and follow the linked instructions. The example below shows three entitlements configured.
Minimum setup completeYou've now completed the minimum requirements to get App Management working properly. If you need to migrate historical subscription activity, see the Migration section below.
Webhooks
Once Recurly processes a real-time notification from Apple or Google and updates the subscription data, it can send a webhook notification specific to the subscription event — for example, subscriber canceled. To receive those webhooks, see configuring Recurly to send webhooks.
Migration
Due to limitations with the Apple and Google App Stores, Recurly can't automatically ingest historical data from the app stores on your behalf. This includes any app store subscriptions created before you started using Recurly App Management. To reflect that data in Recurly, you'll need to backfill our records with the subscription and customer information stored on your side.
This backfill process can be performed using Recurly's API. If you'd like help, the Professional Services team can either guide you through using the API or perform the import on your behalf. Contact the support team to request a paid engagement with the Professional Services team.
