API support and webhooks

This page provides detail about the API endpoints involved with App Management, and the webhook events that are triggered as part of subscription lifecycle events

REST API endpoints

The following REST API endpoints allow you to programmatically pull pertinent information in a JSON format from Recurly regarding your mobile app subscriptions.

External products

These endpoints are used to view information related to the External Products you configured during setup.

External subscriptions

These endpoints are used to view information about external subscriptions, which are Apple or Google subscriptions that your customers have purchased.

Entitlements

This endpoint is used to view information about the entitlements granted to a specific customer (aka: account).

For a complete list of the endpoints specific to App Management, start at External Subscription and scroll down.

Webhooks

For pertinent events in the subscription lifecycle, Recurly triggers a webhook. This allows you to take any subsequent action (e.g., e-mail your customer) based on that webhook notification.

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. The below XML and JSON representations show an example of a webhook notification for a new External subscription. To get more info about the subscription, you would then utilize the Fetch an External Subscription endpoint with the "id" provided in the webhook.

{
  "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>

Configuring Recurly to send webhooks

To configure Recurly to send webhooks specific to Recurly App Management, navigate to Integrations -> Webhooks within Recurly. From the top right, click Configure . Depending on what works best for you, you can either create a New Endpoint, or select Options -> Edit for an existing endpoint. When configuring the endpoint, scroll down to view the External Subscription section of webhooks. For any event that you are interested in, select the checkbox corresponding to that event. For more detail about those events, read the next section. If you want to learn more about Recurly webhooks in general, visit our Webhooks developer documentation.

Complete list of webhook events

The following tables provides a complete list of the webhooks Recurly will send related to mobile app subscriptions. Each webhook maps to a specific Apple or Google notification, as shown below in the table. To see JSON and XML examples for each of the webhooks listed below, view the External Subscription Notifications section of the Webhooks page in our Recurly Development Hub.

Recurly EventApple EventGoogle Event
canceledDID_CHANGE_RENEWAL_STATUS > AUTO_RENEW_DISABLEDSUBSCRIPTION_CANCELED
created (i.e., new subscription)SUBSCRIBED > INITIAL_BUYSUBSCRIPTION_PURCHASED
downgradedDID_CHANGE_RENEWAL_PREF > DOWNGRADEN/A
expiredEXPIRED > VOLUNTARY
EXPIRED > BILLING_RETRY
EXPIRED > PRICE_INCREASE
SUBSCRIPTION_EXPIRED
extended_renewalRENEWAL_EXTENDEDSUBSCRIPTION_DEFERRED
failed_renewalDID_FAIL_TO_RENEWSUBSCRIPTION_ON_HOLD
failed_renewal_with_grace_periodDID_FAIL_TO_RENEW > GRACE_PERIODSUBSCRIPTION_IN_GRACE_PERIOD
pause_schedule_changedN/ASUBSCRIPTION_PAUSE_SCHEDULE_CHANGED
pausedN/ASUBSCRIPTION_PAUSED
price_change_confirmedN/ASUBSCRIPTION_PRICE_CHANGE_CONFIRMED
reactivatedDID_CHANGE_RENEWAL_STATUS > AUTO_RENEW_ENABLEDSUBSCRIPTION_RESTARTED
recoveredN/ASUBSCRIPTION_RECOVERED
refundedREFUNDN/A
refund_declinedREFUND_DECLINEDN/A
refund_reversedREFUND_REVERSEDN/A
renewedDID_RENEW
DID_RENEW > BILLING_RECOVERY
SUBSCRIPTION_RENEWED
resubscribedSUBSCRIBED > RESUBSCRIBEN/A
revokedN/ASUBSCRIPTION_REVOKED
upgradedDID_CHANGE_RENEWAL_PREF > UPGRADEN/A

Viewing triggered webhooks

All triggered webhooks are viewable within Recurly by navigating to Integrations -> Webhooks. In addition, when viewing the details of an Account or External Subscription, there is a link for Webhooks that will take you to a filtered view of the triggered webhooks.