App Subscription Cancellation Flow

At times, users may decide to terminate their subscription, whether it's the primary subscription of the app or a similar service. In such cases, the user initiates the cancellation process by selecting the 'Uninstall' call-to-action (CTA) or a cancel button.

Required Configuration

To receive notifications about updates to a subscription, as outlined in steps 3 and 5 below, the app must register for the "Subscription Updated" webhook. This registration process enables your app to be promptly informed about any changes to its subscription. For more details, please refer to the Subscription Updated webhook documentation.

Step-by-Step Process:

1. Initiation of Cancellation: Users may cancel their subscription, be it the app's main subscription or a similar one. This is initiated by the user clicking on the 'Uninstall' call-to-action (CTA), clicking a cancellation button, or canceling the subscription directly by the billing system.
2. Confirmation of Cancellation: The user must confirm their intent to cancel the subscription.
3. Subscription Update: The underlying subscription is updated upon confirmation, and the Subscription Update webhook is fired. The webhook payload includes the subscription object:
   1. is_active = true
   2. purchase_state = Cancled
   3. cancellation_date = set (the date of cancellation request)

Example of the Subscription object:

{
  "entity_name": "purchasable_subscription",
  "event_type": "update",
  "data": {
    "uid": "3d3dc97a-7ea7-42d7-a287-9993530721fd",
    "display_name": "myappcodename",
    "purchasable_uid": "ee655c26-4a57-48df-8e2e-f85a994b335c",
    "buyer_uid": "ny1g1gau6o3x3yat",
    "business_uid": "ato1v2g3eg3xkyqm",
    "purchase_currency": "USD",
    "purchase_price": "5.00",
    "purchase_state": "canceled",
    "cancellation_date": null,
    "expiration_date": null,
    "updated_at": "2024-03-17T12:27:10.000Z",
    "created_at": "2024-03-01T12:27:09.966Z",
    "payment_type": "monthly",
    "bundled_from_subscription_uid": null,
    "is_active": true
    }
}

4. Final Status Update: The subscription status changes to 'Expired' when the expiration date is reached. This change activates another Subscription Update webhook with the subscription object as payload:
   1. is_active = false
   2. purchase_state = expired
   3. cancellation_date = the date of cancellation request
   4. expiration_date =the date of actual expiration

📘

At this stage, the app no longer has a valid token for the business, so no Get Subscription API call can be made.

5. Triggering Additional Webhooks: If the cancellation process includes uninstalling an app, an App Uninstall webhook is also triggered.

Once verified that the subscription has expired and is no longer valid, i.e. is_active=false, it is up to the app to take action to close down any related service, access, or like that it provided the business.