App Management
App Management gives you a complete, cross-platform picture of your subscription business by syncing App Store and web data, centralizing lifecycle notifications, and streamlining entitlements.
This feature requires an additional cost. Contact Recurly Sales for pricing details.
Definition
Key benefits
How App Management works
At a high level, Recurly listens to real-time notifications from the Apple App Store and Google Play Store, processes subscription-related events, and gives you a clear view into the lifecycle of every mobile app subscription. The walkthrough below covers how it works and the key technical requirements.
1. Uniquely identifying your customers
For Recurly to properly associate a subscription event from Apple or Google, it needs a unique ID for each customer. Recurly looks for that ID in the notification from Apple or Google, so it's important that these unique IDs are built into the subscription purchasing workflows in your mobile apps.
- For Apple subscriptions, appAccountToken is the unique ID. To learn how to set this UUID, see Apple's appAccountToken documentation.
- For Google subscriptions, obfuscatedExternalAccountId is the unique ID. To set it within your billing flow, see Google's setObfuscatedAccountId method and the ExternalAccountIdentifiers reference.
- To conform with Recurly accounts, the unique ID must be 50 characters or less.
- Once established for a customer, the unique ID should not change.
To help you decipher that unique ID in Recurly and see details like name and email, Recurly needs you to share that contact information once per customer. There are a few ways to do this, depending on your preferred workflow.
Scenario 1: A brand new customer subscribes through your mobile app
Recurly isn't yet aware of the new customer and doesn't have an account for them, so you have two options — pick whichever fits your workflow best.
Option 1: Create the account before purchase
Before the customer purchases, POST to Create an account using the unique ID as the code, and share details like name and email. When Recurly receives a notification for that unique ID, the subscription activity is automatically associated with the correct account and customer details are immediately available.
If a requirement prevents you from using the unique ID (appAccountToken for Apple, obfuscatedExternalAccountId for Google) as the code, you can still use your own naming convention (for example, acme|UUID) for the code. In that case, you must provide the unique ID as external_account_code within external_accounts when you POST — this step ensures Recurly can match incoming notifications to the correct account.
Option 2: Update the account after purchase
After the customer purchases, PUT to Update an account using the unique ID as the account code for account_id, and share details like name and email — for example, PUT /accounts/code-UNIQUE_ID with those details. The outcome is the same as Option 1, because Recurly automatically creates a customer account when the first subscription purchase occurs.
This option assumes the unique ID (appAccountToken for Apple, obfuscatedExternalAccountId for Google) is the account_id. It doesn't work if you use a different convention for your Recurly account.
Scenario 2: An existing web customer purchases a mobile app subscription
This is typically a temporary scenario as a customer transitions from a web subscription to a mobile app subscription. Recurly already has an account for this customer, so to connect their mobile app subscription to it, POST to Create an external account to associate their unique ID with the existing account. Otherwise, the customer may appear in Recurly under two different accounts.
Assuming the customer shouldn't end up with two subscriptions, you'll likely want to cancel the web-based subscription with a PUT to Cancel a subscription.
Recurly is flexible and offers several API endpoints to support your workflow.
2. Receiving real-time notifications
After you complete the step-by-step process to connect and configure App Management, Recurly begins receiving real-time notifications about subscription activity in your mobile apps. This keeps Recurly aware of important events — like a new subscription purchase or a failed renewal. Depending on the notification, Recurly uses the provided API key to pull additional information for a complete picture of the event.
3. Updating Recurly with subscription lifecycle activity
For each event, Recurly maps the subscription to the corresponding customer account. For example, when a paid renewal event arrives, Recurly records that renewal for the correct account and associates a paid invoice showing the amount.
4. Notifying you for subsequent actions
Immediately after processing the notification, Recurly triggers the respective webhook to your endpoint. This lets you take any follow-up action — such as emailing your customer — based on that webhook notification.
Continue through the subpages to see how to set up App Management and learn how to use it day to day.
Helpful resources
To hear more about App Management and see a walkthrough, watch these two on-demand webinars.