Access Management using webhooks

Clear and simple access management is important for a smooth customer subscription experience. With our subscription APIs and webhooks, Paddle makes it easy for you to implement this.

Subscription Lifecycle

You may find "Subscription basics: The Subscription Lifecycle" useful for learning more about how to approach subscription billing

After purchasing a subscription, your customers' subscription status will change based on whether we are able to continue charging them for access to a plan.

Subscribing to webhooks in your vendor dashboard (Developer Tools > Events) allows you to keep your system in sync. You should enable the alerts for:

All of these include the fields subscription_id and passthrough, with the latter containing any custom data that you want to pass through (for example, your system's user ID).

In order to use most of our Subscription APIs for automating subscription management, it is important to store the subscription_id from the Subscription Created webhook alert in your database system when a customer has subscribed to your product/service.

This allows you to use most of our Subscription APIs including Metered Billing, Update Payment Details, Upgrade/Downgrade, and Cancel/Pause subscription.

Subscription Created

Whenever a customer successfully subscribes to a subscription plan, the subscription_created alert will trigger, and from within it store the subscription_id in your database against that user. You may also want to store the update_url and cancel_url as well for later use.

You will also receive a subscription_payment_succeeded alert where the initial_payment is 1. Store the relevant information needed (e.g. order_id, next_payment_amount, sale_gross, quantity, status etc.) and allow that customer access to the product/service till the next_bill_date.

Subscription Updated

When the customer's subscription is updated, such as if the plan, price, quantity, status of their subscription changes, or if the next payment date is rescheduled manually, you will receive the subscription_updated alert.

You should update your records with the updated information (e.g. next_bill_date, status, update_url, cancel_url, new_quantity, new_price etc.).

If the status is active, continue allowing product/service access up till the next_bill_date. Else, you may want to restrict access.

Rebilling

Successful Rebilling

For each successful rebilling, you will receive a subscription_payment_succeeded alert (initial_payment is 0). Get the subscription_id and update your records with the relevant updated information (e.g. next_bill_date, status). If the status remains active, continue allowing your customer access to the product/service till the next_bill_date.

Failed Rebilling

As subscriptions are recurring in nature, rebilling can sometimes fail. This can happen for a variety of reasons, such as an expired payment details, or their payment method temporarily having insufficient funds. Learn more how you can set your preferred retry rules as well as its behaviour here.

When a rebilling fails for the first time, a subscription_updated alert will be triggered (with the status as past_due and the old_status as active). You may want to display a warning to the customer within your product/service when this happens.

Each time a payment fails, a subscription_payment_failed event is triggered. You can use this event to monitor failed payments and update your records accordingly (e.g. next_retry_date, attempt_number, update_url, cancel_url etc.).

If Paddle's "Failed Payment Email" notification has been enabled, customers will be able to update their payment details using the link included within the email. Once the payment update is completed and the customer is charged successfully, you will receive a subscription_updated alert (status is active and the old_status is past_due) as well as the subscription_payment_succeeded alert. Product/service access should restart and remain live till the next_bill_date.

Past Due Subscription

If the "Move to past due" option is selected in the retry rules, the customer will stay in the past-due state for an indefinite time should their payment fail. If they update their payment method for the subscription, they will be charged all of the missed rebilling that were due during the time period they were in this state. When this happens, the subscription_updated alert (containing the update_url, cancel_url) will trigger, followed by a subscription_payment_succeeded alert for each missed rebilling successfully charged. You should only use this option if:

You would like to continue allowing the customer access to the product/service while they're past-due
Customer is aware that they will be rebilled for all of the payments missed during this time when their payment details are updated successfully.

Subscription Paused

This is only applicable if subscriptions are set to pause following the failure of all subscription payment retries, or if you manually pause the subscription via the dashboard or API as described here.

When a subscription is requested to be paused, a subscription_updated alert will be triggered to indicate that the subscription is scheduled to be paused (with the paused_at, paused_from and paused_reason populated) - the status will remain active until the paused_from date - you should continue allowing your customer access to the product/service until this date.

When the paused_from date elapses, a second subscription_updated alert will be triggered to indicate that the subscription status is successfully paused (with the old_status as active). When this happens you should restrict the customer's access to the product/service indefinitely.

If the subscription is unpaused before the paused_from date, a subscription_updated alert will be triggered immediately with the subscription status still active, but the paused_at, paused_from and paused_reason fields removed from the alert.

If the subscription is unpaused after the paused_from date, a subscription_updated alert will be triggered immediately, with the status as past_due and the old_status as paused. We will then attempt to charge the buyer immediately;

If this is successful, a second subscription_updated alert (statusis active, old_status is past_due) will be received along with the subscription_payment_succeeded alert, and the billing cycle will restart from that day onwards. You should update your records and allow product/service access up till the next_bill_date.
If this is unsuccessful, a second subscription_updated alert (status and old_status is both past_due) will be received along with the subscription_payment_failed alert (containing new update_url and cancel_url), and your payment retry rules set within your Recover Settings page will come into effect. The customer's product/service access should remain restricted.

Subscription Cancelled

When a customer cancels their subscription or if the "Cancel Subscription" option is selected in the retry rules, you will receive the subscription_cancelled alert. Get the subscription_id along with the cancellation_effective_date within it and update your records - you should allow the customer continued access to the product/service up till this date.

If the last payment is also refunded and you wish to revoke access immediately you can listen to the subscription_payment_refunded alert, match the subscription_id to the canceled subscription, and set the product/service to be stopped immediately.