Paddle.js events
Paddle.js emits events as part of the checkout journey. Use events to update elements in your frontend for inline checkout, or for analytics purposes.
As a customer moves through the checkout, Paddle.js emits events for key actions like:
- When the checkout is opened, closed, or completed
- When customer information is added, updated, or removed
- When items are added, removed, or updated
- When payments are attempted and outcomes of payment attempts
- When discounts are added or removed
You can pass an eventCallback parameter as part of the Paddle.Initialize() method to run behaviors based on customer interactions with your checkout. You'll typically use this to show and update on-page information when building an inline checkout.
Attributes
Name of this event, in the format entity.event_type.
Event payload.
Unique Paddle ID for this checkout, prefixed with che_.
Unique Paddle ID for the transaction related to this checkout, prefixed with txn_.
Status of this checkout.
Key-value pairs of custom data. Must be valid JSON and contain at least one key.
Supported three-letter ISO 4217 currency code for this checkout.
Information about the customer on this checkout.
Items to bill for.
Financial breakdown of the total for this checkout, calculated by Paddle.
Financial breakdown of the recurring total for this checkout, calculated by Paddle. Only included where there are recurring items.
Information about the payment details used on this checkout.
Checkout settings.
Information about the discount applied to this checkout. Only included when a discount is applied.
Common attributes
When building an inline checkout, you can write an event callback function to present totals and other information.
Here are some commonly used fields in Paddle.js events that you might like to use in your implementation:
data.items[].product.name | Product name for itemized breakdowns. |
data.items[].price_name | Price name. Typically describes how often this item bills. |
data.items[].trial_period | Details about the trial period for an item, if any. |
data.items[].billing_cycle | How often an item is billed, if recurring. |
data.items[].totals.subtotal | Total for an item, excluding tax and discount. |
data.totals.total | Grand total for a transaction, including tax and discount. |
data.recurring_totals.total | Recurring total for a transaction, including tax and discount. |
(data.totals.total - data.recurring_totals.total) | Where transactions contain a mix of one-time charges and recurring items, subtract a value in data.recurring_totals from the corresponding value in data.totals to calculate one-time charge totals. |
For compliance and the best customer experience, inline checkout implementations must include a description of what's being purchased, transaction totals, billing frequency (if recurring), and information about any trial periods (if applicable).
List of events
| Event name | Details |
|---|---|
checkout.loaded | Checkout created and loaded on the page. |
checkout.closed | Checkout closed on the page. |
checkout.completed | Checkout completed successfully. |
checkout.items.updated | Item updated on the checkout. For example, a quantity change. |
checkout.items.removed | Item removed from the checkout. |
checkout.customer.created | Customer created. |
checkout.customer.updated | Customer information updated. This includes business and address information. |
checkout.customer.removed | Customer removed from the checkout, meaning they clicked 'Not you?' to reenter their details. |
checkout.payment.selected | Payment method selected. |
checkout.payment.initiated | Customer attempted payment using the selected payment method. |
checkout.payment.failed | Payment attempt failed. |
checkout.discount.applied | Discount applied to the checkout. |
checkout.discount.removed | Discount removed from the checkout. |
checkout.warning | Warning occurred on the checkout. |
checkout.error | Error occurred on the checkout. |
