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.
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
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.
marketing_consent string The value of this field “1” or “0” indicates whether the user has agreed to receive marketing messages from the vendor.
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.
marketing_consent string The value of this field “1” or “0” indicates whether the user has agreed to receive marketing messages from the vendor.
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.
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.
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.
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.
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.
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.
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.

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.
marketing_consent string The value of this field “1” or “0” indicates whether the user has agreed to receive marketing messages from the vendor.
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.
marketing_consent string The value of this field “1” or “0” indicates whether the user has agreed to receive marketing messages from the vendor.
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.
checkout_id int(11) The checkout id of the created transaction.
customer_name string Customer name.
user_id string Customer user id.
plan_name string Subscription plan name.
payment_tax int(11) Amount of tax paid as a result of this payment.
payment_method string Payment method used to make the transaction.
status string Subscription status.
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_tax        decimal        The amount of tax received from the customer, in the vendor’s default currency at the time of the transaction.        
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.       
coupon        string        Coupon code of any coupon associated with this payment.        
receipt_url        string        Url containing the customer receipt.        
initial_payment        boolean        If it is the customer first payment.        
instalments        int        Number of payments made to date.        
quantity int(11) The quantity applied to the subscription. Please note that this will only be returned if the subscription has quantity enabled.
unit_price decimal The price per unit of the subscription. Please note that this will only be returned if the subscription has quantity enabled.

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.
marketing_consent string The value of this field “1” or “0” indicates whether the user has agreed to receive marketing messages from the vendor.
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. Please note that this parameter will only be returned if the subscription has quantity enabled.
amount float 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.
quantity int(11) The quantity applied to the subscription. Please note that this will only be returned if the subscription has quantity enabled.
unit_price decimal The price per unit of the subscription. Please note that this will only be returned if the subscription has quantity enabled.

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.
checkout_id int(11) The checkout id of the transaction being refunded.
currency string(3) The three letter ISO currency code of the transaction. Eg: USD, GBP
email string The email address of the customer this refund is being sent to.
marketing_consent string The value of this field “1” or “0” indicates whether the user has agreed to receive marketing messages from the vendor.
event_time datetime (yyyy-mm-dd HH:mm:ss) The date and time this refund was issued.
initial_payment Boolean If the payment being refunded refers to the first payment.
instalments int Number of payments made by the customer to date.
order_id int(11) The Paddle Order ID that is being refund. This can be used to lookup the order within your Paddle account.
passthrough string This field contains any values that you passed into the checkout using the ‘passthrough’ parameter. (See: Checkout Documentation)
subscription_id int(11) The subscription id associated with this refund.
subscription_payment_id int(11) The subscription payment id.
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)
gross_refund        decimal        The total amount returned to the customer as a result of this refund, in the currency of the original transaction.       
tax_refund        decimal        The amount of tax returned to the customer, in the currency of the original transaction.       
fee_refund        decimal        The fee amount returned to the vendor, in the currency of the original transaction.        
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%).       
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_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.        
balance_fee_refund        decimal        The fee amount returned to the vendor, in the vendor’s default currency at the time of the transaction.        
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%).      
quantity int(11) The quantity applied to the subscription. Please note that this will only be returned if the subscription has quantity enabled.
unit_price decimal The price per unit of the subscription. Please note that this will only be returned if the subscription has quantity enabled.
Was this page helpful?