Integration best practices

Best practices for configuring, testing, syncing, and building on App Management — covering sandbox testing, data migration, external products, webhooks, and automated exports.

This guide collects the best practices for a successful App Management integration — how to configure and test with sandbox data, sync and migrate historical data safely, set up external products, and build reliable workflows on webhooks and the API. Follow these recommendations to avoid the common pitfalls before you go live in production.

Additional cost
This feature requires an additional cost. Contact Recurly Sales for pricing details.

1Configuration 2Testing 3Data sync 4External products 5Webhooks and API 6Automated exports

NoteIf you're already successfully viewing Apple or Google subscription lifecycle events within Recurly, you're welcome to skip this guide.

Configuration

Before you can use any App Management features — or prepare for migration — you need to configure App Management on your Recurly site. There are step-by-step guides for both the Apple App Store and the Google Play Store on your Recurly subdomain:

Testing

Before configuring App Management with your production data, we strongly recommend starting with sandbox or test data from each external store. Apple and Google each handle testing differently, and working through all your use cases is crucial to a successful integration.

Apple

Apple lets developers use a Sandbox Server URL endpoint for testing. If that term is unfamiliar, you may need to set up your Sandbox Server URL in App Store Connect — see Apple's guide on entering server URLs for App Store Server Notifications, under "Enter a URL for testing App Store Server Notifications in a Sandbox environment." When configuring your sandbox site in Recurly, edit the Sandbox Server URL instead of your Production Server URL.

Google

Google uses Pub/Sub topics for notifications and only allows notifications to go to one topic. However, you can create a second subscription to the same Pub/Sub topic for testing. Both endpoints, defined in their respective Pub/Sub subscriptions, receive all test and production notifications. Recurly evaluates every payload and denotes whether the notification is production or test, so you'll likely see both flowing to your non-production and production Recurly subdomains. You can read more in the testing guidance for Using App Management. If you have two apps — for example, one for dev and one for production — you can use your dev app and its Pub/Sub topic on your sandbox site in Recurly for testing.

Data sync

Once you've configured the external stores to your Recurly site, whether for sandbox or production, they'll sync and send their notifications to Recurly. We don't ignore or delete notifications — we store them until we can successfully process them. To process a notification and associate it with a subscription event from Apple or Google, Recurly needs a unique ID established for each customer, which we look for in the notification from each platform. It's important that these unique IDs are built into your subscription purchasing workflows for Apple and Google. Learn more about uniquely identifying your customers.

If you have any historical data within the platforms, you'll need to migrate it into Recurly so we can properly process notifications related to those historical accounts and subscriptions — and generate unique IDs for them if you haven't already.

WarningDon't turn on the production sync before you're ready for migration. Doing so can lead to issues with the integration.

When you're live on your production site with App Management, we'll create a shared folder on Google Drive to send you a daily report of unprocessed notifications. Use this report to determine what's needed for those external subscriptions — in most cases, you'll just need to import them.

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. Learn more about creating external products. If you don't make the association, the purchases go to unassigned purchases.

ImportantUpgrades and downgrades in Recurly for Apple subscriptions can behave unexpectedly depending on how you set up your Subscription Order in App Store Connect. Make sure your highest upgrade is "1" and your lowest downgrade is the highest number. If numbers are shared between subscriptions, they may be treated as a downgrade when changing between them.

Webhooks and API

Recurly follows industry standards and doesn't recommend using webhooks as your source of truth. Webhooks may arrive out of order, be retried, or be sent multiple times due to failed delivery or other server errors. Make sure your endpoint can handle receiving the same notification multiple times and out of order. Webhook payloads can be JSON or XML.

Before processing a webhook, send Recurly a success response — this prevents Recurly from resending it. After sending the receipt, process the webhook.

The API is the most reliable data source, so always make an API call when you receive a webhook you act on, such as one that triggers a customer email. Use the receipt of the webhook to trigger an API query that validates the notification details against current API data. Use the latest version of the API (currently v2021-02-25) to ensure access to the newest features.

Automated exports

Automated Exports are a more efficient and reliable way to get data than cycling through resources in the API, and they work well for data warehousing. We offer Automated Exports for External Subscriptions and External Invoices. They can track events triggered in the last 24 hours, keeping your systems no more than a day out of sync.

Updated 13 days ago

Did this page help you?