Fill in the form to arrange a demo

Subscriptions Event Reference

The easiest way to keep your system in sync with Paddle is by subscribing to webhooks. We send a HTTP POST request 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 Alerts

Below is a list of subscription 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 customer 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.
subscription_payment_refunded Fields Fired when a refund for a subscription payment is issued.

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
alert_name string subscription_created
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 customer in your database.
checkout_id string The checkout id of the created transaction.
currency string (3) The three letter ISO currency code of the order. Eg: USD, GBP.
email string The email address of the subscribed customer.
event_time UTC datetime (yyyy-mm-dd HH:mm:ss) The date and time this subscription was created.
marketing_consent int(11) The value of this field “1” or “0” indicates whether the customer has agreed to receive marketing messages from the vendor.
next_bill_date date (yyyy-mm-dd) The date the next payment is due on this subscription.
passthrough string This field contains any values that you passed into the checkout using the ‘passthrough’ parameter. See the Paddle Checkout (Web) documentation for more information.
quantity int(11) The quantity applied to the subscription.
status string This is the current status of the subscription. A list of possible values and their meanings can be found here.
subscription_id int(11) This is the unique Subscription ID for this customer’s subscription. You should store this with the customer in your database, as it is needed for making API calls.
subscription_plan_id int(11) The ID of the Subscription Plan the customer is subscribed to. (This is the value that will change upon plan change).
unit_price decimal The price per unit of the subscription.
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 customer in your database.
p_signature string This field contains an encrypted token that you can use to verify the request authenticity. (See: Verifying Webhooks)

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
alert_name string subscription_updated
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 customer in your database.
checkout_id string The checkout id of the transaction being updated.
email string The email address of the subscribed customer.
event_time UTC datetime (yyyy-mm-dd HH:mm:ss) The date and time this subscription was updated.
marketing_consent int(11) The value of this field “1” (true) or “0” (false) indicates whether the customer has agreed to receive marketing messages from the vendor.
new_price decimal The new total recurring price of the subscription. Please note that this will only be returned if the subscription has quantity enabled.
new_quantity int(11) The new quantity applied to a quantity enabled subscription. Please note that this will only be returned if the subscription has quantity enabled.
new_unit_price decimal The new price per unit of the subscription. Please note that this will only be returned if the subscription has quantity enabled.
next_bill_date date (yyyy-mm-dd) The date the next payment is due on this subscription.
old_price decimal The previous total recurring price of the subscription. Please note that this will only be returned if the subscription has quantity enabled.
old_quantity int(11) The previous quantity applied to the subscription. Please note that this will only be returned if the subscription has quantity enabled.
old_unit_price decimal The previous price per unit of the subscription. Please note that this will only be returned if the subscription has quantity enabled.
passthrough string This field contains any values that you passed into the checkout using the ‘passthrough’ parameter. See the Paddle Checkout (Web) documentation for more information.
status string This is the current status of the subscription. A list of possible values and their meanings can be found here.
subscription_id int(11) This is the unique Subscription ID for this customer’s subscription. You should store this with the customer in your database, as it is needed for making API calls.
subscription_plan_id int(11) The ID of the new Subscription Plan the customer has subscribed to.
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 customer in your database.
p_signature string This field contains an encrypted token that you can use to verify the request authenticity. (See: Verifying Webhooks)
old_next_bill_date date (yyyy-mm-dd) The next bill date before the subscription was updated.
old_status string The subscription state before the subscription was updated. List of possible values and their meanings can be found here.
old_subscription_plan_id int(11) The ID of the subscription plan before the subscription was updated.

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
alert_name string subscription_cancelled
cancellation_effective_date date (yyyy-mm-dd) The date the cancellation should come into effect, taking the customer’s balance into account.
checkout_id string The checkout id of the transaction being cancelled.
currency string (3) The three letter ISO currency code of the order. Eg: USD, GBP.
email string The email address of the subscribed customer.
event_time UTC datetime (yyyy-mm-dd HH:mm:ss) The date and time this subscription was cancelled.
marketing_consent int(11) The value of this field “1” (true) or “0” (false) indicates whether the customer has agreed to receive marketing messages from the vendor.
passthrough string This field contains any values that you passed into the checkout using the ‘passthrough’ parameter. See the Paddle Checkout (Web) documentation for more information.
quantity int(11) The quantity applied to the subscription.
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.
subscription_id int(11) This is the unique Subscription ID for this customer’s subscription. You should store this with the customer in your database, as it is needed for making API calls.
subscription_plan_id int(11) The ID of the Subscription Plan the customer is subscribed to. (This is the value that will change upon plan change).
unit_price decimal The price per unit of the subscription.
user_id int(11) The customer user id.
p_signature string This field contains an encrypted token that you can use to verify the request authenticity. (See: Verifying Webhooks)

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
alert_name string subscription_payment_succeeded
balance_currency        string(3)        The three letter ISO currency code of the vendor’s default currency at the time of the transaction. Eg: USD, GBP.
balance_earnings        decimal        Amount of balance increase as a result of this payment.       
balance_fee        decimal        The fee amount taken from the vendor, in the vendor’s default currency at the time of the transaction.        
balance_gross        decimal        The total amount received from the customer as a result of the payment, in the vendor’s default currency at the time of the transaction.       
balance_tax        decimal        The amount of tax received from the customer, in the vendor’s default currency at the time of the transaction.        
checkout_id string The checkout id of the created transaction.
country string The two-letter ISO country code of the customer.
coupon        string        Coupon code of any coupon associated with this payment.        
currency string The three-letter ISO currency code of the order.
customer_name string Customer name.
earnings decimal The total amount (after taxes and fees) you earned from this payment.
email string The email address of the subscribed customer.
event_time UTC datetime (yyyy-mm-dd HH:mm:ss) The date and time this subscription payment succeeded.
fee decimal The total amount in Paddle fees for this payment.
initial_payment        int(11)        The value of this field “1” (true) indicates whether it is the customer’s first payment for this subscription.        
instalments        int        Number of payments made to date.        
marketing_consent int(11) The value of this field “1” (true) or “0” (false) indicates whether the customer has agreed to receive marketing messages from the vendor.
next_bill_date date (yyyy-mm-dd) The date the next payment is due on this subscription.
order_id string An ID that references the transaction/ payment within Paddle.
passthrough string This field contains any values that you passed into the checkout using the ‘passthrough’ parameter. See the Paddle Checkout (Web) documentation for more information.
payment_method string Payment method used to make the transaction.
payment_tax decimal Amount of tax paid as a result of this payment.
plan_name string Subscription plan name.
quantity int(11) The quantity applied to the subscription.
receipt_url        string        URL containing the customer receipt.        
sale_gross decimal The total amount the customer was charged for this payment.
status string Subscription status.
subscription_id int(11) This is the unique Subscription ID for this customer’s subscription. You should store this with the customer in your database, as it is needed for making API calls.
subscription_plan_id int(11) The ID of the Subscription Plan the customer is subscribed to. (This is the value that will change upon plan change).
unit_price decimal The price per unit of the subscription.
user_id int(11) The customer user id.
p_signature string This field contains an encrypted token that you can use to verify the request authenticity. (See: Verifying Webhooks)

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
alert_name string subscription_payment_failed
amount decimal The amount that we tried to charge for this payment. Please note that this parameter will only be returned if the subscription has quantity enabled.
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 customer in your database.
checkout_id string The checkout id of the created transaction.
currency string The three-letter ISO currency code of this payment attempt. Please note that this parameter will only be returned if the subscription has quantity enabled.
email string The email address of the subscribed customer.
event_time UTC datetime (yyyy-mm-dd HH:mm:ss) The date and time this subscription payment had failed.
marketing_consent int(11) The value of this field “1” (true) or “0” (false) indicates whether the customer has agreed to receive marketing messages from the vendor.
next_retry_date date (yyyy-mm-dd) The date that we will next try to process this failed payment.
passthrough string This field contains any values that you passed into the checkout using the ‘passthrough’ parameter. See the Paddle Checkout (Web) documentation for more information.
quantity int(11) The quantity applied to the subscription. Please note that this will only be returned if the subscription has quantity enabled.
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.
subscription_id int(11) This is the unique Subscription ID for this customer’s subscription. You should store this with the customer in your database, as it is needed for making API calls.
subscription_plan_id int(11) The ID of the Subscription Plan the customer is subscribed to. (This is the value that will change upon plan change).
unit_price decimal The price per unit of the subscription. Please note that this will only be returned if the subscription has quantity enabled.
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 customer in your database.
p_signature string This field contains an encrypted token that you can use to verify the request authenticity. (See: Verifying Webhooks)

Subscription Payment Refunded

Identify this event with the HTTP POST parameter alert_name with a value of subscription_payment_refunded. Note that if a refund is issued for the initial payment of a subscription, we will send a payment_refunded alert in addition.

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

Field Type/Format Description
alert_name string subscription_payment_refunded
amount decimal The amount refunded, partial refunds are possible.
balance_currency        string(3)        The three letter ISO currency code of the vendor’s default currency at the time of the transaction. Eg: USD, GBP.       
balance_earnings_decrease        decimal        The amount of revenue taken from the vendor’s earnings as a result of this refund, in the vendor’s default currency at the time of the transaction.  It returns a positive or negative value. Eg: If you issue a VAT only refund, this will increase the vendor’s earnings instead of decreasing it, to reflect this we use a negative value. Please also note that if the earnings of the order being refunded are being split between vendors, the earnings decrease amount will not include the other vendor’s fee, only yours. (eg. If you are giving 15% of your earnings to another vendor and keeping 85%, your balance earnings will be reduced only by 85%).      
balance_fee_refund        decimal        The fee amount returned to the vendor, in the vendor’s default currency at the time of the transaction.        
balance_gross_refund        decimal        The total amount returned to the customer as a result of this refund, in the vendor’s default currency at the time of the transaction.       
balance_tax_refund        decimal        The amount of tax returned to the customer, in the vendor’s default currency at the time of the transaction.        
checkout_id string The checkout id of the transaction being refunded.
currency string(3) The three letter ISO currency code of the transaction. Eg: USD, GBP
earnings_decrease        decimal          The amount of revenue taken from the vendor’s earnings as a result of this refund, in the currency of the original transaction.  It returns a positive or negative value. Eg: If you issue a VAT only refund, this will increase the vendor’s earnings instead of decreasing it, to reflect this we use a negative value. Please also note that if the earnings of the order being refunded are being split between vendors, the earnings decrease amount will not include the other vendor’s fee, only yours. (eg. If you are giving 15% of your earnings to another vendor and keeping 85%, your balance earnings will be reduced only by 85%).       
email string The email address of the customer this refund is being sent to.
event_time UTC datetime (yyyy-mm-dd HH:mm:ss) The date and time this refund was issued.
fee_refund        decimal        The fee amount returned to the vendor, in the currency of the original transaction.        
gross_refund        decimal        The total amount returned to the customer as a result of this refund, in the currency of the original transaction.       
initial_payment int(11) The value of this field “1” (true) indicates whether the payment being refunded is the customer’s first payment.
instalments int Number of payments made by the customer to date.
marketing_consent int(11) The value of this field “1” (true) or “0” (false) indicates whether the customer has agreed to receive marketing messages from the vendor.
order_id string The Paddle Order ID that is being refund. This can be used to look up the order within your Paddle account.
passthrough string This field contains any values that you passed into the checkout using the ‘passthrough’ parameter. See the Paddle Checkout (Web) documentation for more information.
quantity int(11) The quantity applied to the subscription.
refund_type string The type of refund, the value of this field can be full, vat or partial .
subscription_id int(11) The subscription id associated with this refund.
subscription_payment_id int(11) The subscription payment id.
tax_refund        decimal        The amount of tax returned to the customer, in the currency of the original transaction.       
unit_price decimal The price per unit of the subscription.
user_id int(11) The customer user id.
p_signature string This field contains an encrypted token that you can use to verify the request authenticity. (See: Verifying Webhooks)

Next Steps

Using Webhooks
Webhooks are HTTP calls to your server that make it really easy for you to receive data and events from Paddle, and for your server to communicate data back.

Questions about Paddle?

If you need any help regarding your Paddle integration, please get in touch with our Customer Success team using the form below.

Questions about Paddle?