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).

List Entitlements granted to an 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 Event	Apple Event	Google Event
canceled	DID_CHANGE_RENEWAL_STATUS > AUTO_RENEW_DISABLED	SUBSCRIPTION_CANCELED
consumption_requested	CONSUMPTION_REQUEST	N/A
created (i.e., new subscription)	SUBSCRIBED > INITIAL_BUY	SUBSCRIPTION_PURCHASED
downgraded	DID_CHANGE_RENEWAL_PREF > DOWNGRADE	N/A
downgrade_canceled	DID_CHANGE_RENEWAL_PREF	N/A
expired	EXPIRED > VOLUNTARY EXPIRED > BILLING_RETRY EXPIRED > PRICE_INCREASE	SUBSCRIPTION_EXPIRED
extended_renewal	RENEWAL_EXTENDED	SUBSCRIPTION_DEFERRED
failed_renewal	DID_FAIL_TO_RENEW	SUBSCRIPTION_ON_HOLD
failed_renewal_with_grace_period	DID_FAIL_TO_RENEW > GRACE_PERIOD	SUBSCRIPTION_IN_GRACE_PERIOD
grace_period_expired	GRACE_PERIOD_EXPIRED	N/A
pause_schedule_changed	N/A	SUBSCRIPTION_PAUSE_SCHEDULE_CHANGED
paused	N/A	SUBSCRIPTION_PAUSED
plan_changed	N/A	SUBSCRIPTION_PURCHASED
price_change_confirmed	N/A	SUBSCRIPTION_PRICE_CHANGE_CONFIRMED
reactivated	DID_CHANGE_RENEWAL_STATUS > AUTO_RENEW_ENABLED	SUBSCRIPTION_RESTARTED
recovered	N/A	SUBSCRIPTION_RECOVERED
refunded	REFUND	N/A
refund_declined	REFUND_DECLINED	N/A
refund_reversed	REFUND_REVERSED	N/A
renewed	DID_RENEW DID_RENEW > BILLING_RECOVERY	SUBSCRIPTION_RENEWED
resubscribed	SUBSCRIBED > RESUBSCRIBE	N/A
resubscribed_incorrect_account	SUBSCRIBED > RESUBSCRIBE	N/A
revoked	N/A	SUBSCRIPTION_REVOKED
upgraded	DID_CHANGE_RENEWAL_PREF > UPGRADE	N/A
voided	N/A	SUBSCRIPTION_VOIDED

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.