Event Reference

The easiest way to keep your system in sync with Paddle is by subscribing to web-hooks. We send a HTTP POST to your webhook endpoint for each action against a subscription (such as a subscription payment, plan change, cancellation).

Subscribing to Alerts

Before you receive any events, you need to define the URL that we should send the HTTP POST requests to.

  • Step 1: Visit your Account Settings page in the Vendor Dashboard.
  • Step 2: Click the "Alerts" tab at the top of the page.
  • Step 3: Check each alert that you wish to receive a notification for.
  • Step 4: If you’re receiving webhook alerts enter a URL that we should send the HTTP POST requests to at the bottom of the page.
  • Step 5: Click the "Save Changes" button to confirm your alerts.

List of Events

Below is a list of events that you can subscribe to. To identify the event you’re being sent use the HTTP POST parameter named alert_name which will contain the Event Name.

Event Parameters Description
subscription_created Fields Fired when a new subscription is created, and a user has successfully subscribed.
subscription_updated Fields Fired when a subscription changes (eg. a customer changes plan via upgrade or downgrade).
subscription_cancelled Fields Fired when a subscription is cancelled/ ended.
subscription_payment_succeeded Fields Fired when a payment for a subscription is received successfully.
subscription_payment_failed Fields Fired when a payment for a subscription fails.

Responding to Events/ Alerts

For webhook events/ alerts, your server should respond with a HTTP 200 status code to indicate you have successfully received the message. If we receive anything other than a HTTP 200 we will retry the call to your webhook URL every hour for a maximum of 72 hours.


Subscription Created

Identify this event with the HTTP POST parameter alert_name with a value of subscription_created

Fields: Each of the below are HTTP POST fields sent with this event.

Field Type/Format Description
subscription_id int(11) This is the unique Subscription ID for this users subscription. You should store this with the user in your database, as it is needed for making API calls.
status string This is the current status of the subscription. A list of possible values and their meanings can be found here.
email string The email address of the subscribed user.
subscription_plan_id int(11) The ID of the Subscription Plan the user is subscribed to. (This is the value that will change upon plan change).
next_bill_date date (yyyy-mm-dd) The date the next payment is due on this subscription.
passthrough string The value of the passthrough field you sent with the initial subscription checkout. This field is usually used to identify the user in your own database.
update_url string A URL of the ‘Update Billing Information’ page. See the documentation for update/ cancellation URLs. You should store this URL along with the subscribed user in your database.
cancel_url string A URL of the ‘Cancellation’ page. See the documentation for update/ cancellation URLs. You should store this URL along with the subscribed user in your database.
currency string (3) The three letter ISO currency code of the order. Eg: USD, GBP.
checkout_id int(11) The checkout id of the created transaction.

Subscription Updated

Identify this event with the HTTP POST parameter alert_name with a value of subscription_updated

Fields: Each of the below are HTTP POST fields sent with this event.

Field Type/Format Description
subscription_id int(11) This is the unique Subscription ID for this users subscription. You should store this with the user in your database, as it is needed for making API calls.
status string This is the current status of the subscription. A list of possible values and their meanings can be found here.
email string The email address of the subscribed user.
subscription_plan_id int(11) The ID of the Subscription Plan the user is subscribed to. (This is the value that will change upon plan change).
next_bill_date date (yyyy-mm-dd) The date the next payment is due on this subscription.
passthrough string The value of the passthrough field you sent with the initial subscription checkout. This field is usually used to identify the user in your own database.
checkout_id int(11) The checkout id of the transaction being updated.
update_url string A URL of the ‘Update Billing Information’ page. See the documentation for update/ cancellation URLs. You should store this URL along with the subscribed user in your database.
cancel_url string A URL of the ‘Cancellation’ page. See the documentation for update/ cancellation URLs. You should store this URL along with the subscribed user in your database.

Subscription Cancelled

Identify this event with the HTTP POST parameter alert_name with a value of subscription_cancelled

Fields: Each of the below are HTTP POST fields sent with this event.

Field Type/Format Description
subscription_id int(11) This is the unique Subscription ID for this users subscription. You should store this with the user in your database, as it is needed for making API calls.
status string This is the current status of the subscription. For cancellations this value will be deleted. - A list of possible values and their meanings can be found here.
email string The email address of the subscribed user.
subscription_plan_id int(11) The ID of the Subscription Plan the user is subscribed to. (This is the value that will change upon plan change).
cancellation_effective_date datetime (yyyy-mm-dd HH:mm:ss) The date the cancellation should come into effect, taking the user’s balance into account.
passthrough string This field contains any values that you passed into the checkout using the ‘passthrough’ parameter. (See: Checkout Documentation)
user_id int(11) The customer user id.
checkout_id int(11) The checkout id of the transaction being cancelled.

Subscription Payment Succeeded

Identify this event with the HTTP POST parameter alert_name with a value of subscription_payment_succeeded

Fields: Each of the below are HTTP POST fields sent with this event.

Field Type/Format Description
subscription_id int(11) This is the unique Subscription ID for this users subscription. You should store this with the user in your database, as it is needed for making API calls.
email string The email address of the subscribed user.
subscription_plan_id int(11) The ID of the Subscription Plan the user is subscribed to. (This is the value that will change upon plan change).
next_bill_date date (yyyy-mm-dd) The date the next payment is due on this subscription.
passthrough string The value of the passthrough field you sent with the initial subscription checkout. This field is usually used to identify the user in your own database.
order_id string An ID that references the transaction/ payment within Paddle.
country string The two-letter ISO country code of the user.
currency string The three-letter ISO currency code of the order.
sale_gross float The total amount the user was charged for this payment.
fee float The total amount in Paddle fees for this payment.
earnings float The total amount (after taxes and fees) you earned from this payment.

Subscription Payment Failed

Identify this alert_name with the HTTP POST parameter event with a value of subscription_payment_failed

Fields: Each of the below are HTTP POST fields sent with this event.

Field Type/Format Description
subscription_id int(11) This is the unique Subscription ID for this users subscription. You should store this with the user in your database, as it is needed for making API calls.
status string This is the current status of the subscription. For failed payments this value will be past_due. - A list of possible values and their meanings can be found here.
email string The email address of the subscribed user.
subscription_plan_id int(11) The ID of the Subscription Plan the user is subscribed to. (This is the value that will change upon plan change).
next_retry_date date (yyyy-mm-dd) The date that we will next try to process this failed payment.
currency string The three-letter ISO currency code of this payment attempt.
amount float The amount that we tried to charge for this payment.
Was this page helpful?