After you activate Paddle Billing for your account, you get access to Paddle Billing data alongside your Paddle Classic data. Paddle Billing and Paddle Classic share some core settings, but most data is separate. This includes customer, catalog, and subscription data.
To move fully to Paddle Billing, you need to replace your integration with Paddle Classic with an integration that uses the Paddle Billing API, webhooks, and Paddle.js v2.
This guide walks through how data in Paddle Classic maps to data in Paddle Billing at a technical level. You can use it to understand how you should build your integration with Paddle Billing.
Shared settings
Paddle Billing is built on the Paddle platform, so it shares core settings with Paddle Classic.
- Account verification
You don't need to verify your domains, business, or identity again. - Your Paddle account settings
Business account settings and team members are the same across Paddle Classic and Paddle Billing. - Checkout customization options
Payment methods, branding options, and other checkout customization options work across Paddle Classic and Paddle Billing. - Your balance and payouts
Earnings from transactions both Paddle Classic and Paddle Billing are added to your balance, and you're paid out using the same payout settings. - Taxable categories
Paddle verifies what kinds of products you're able to offer at the account level, so you don't need to get approval for taxable categories in Paddle Billing if you were approved for them in Paddle Classic. - Allowed IP addresses
Webhooks from Paddle Billing are sent from the same IP addresses as Paddle Classic. - API keys
API keys work for both Paddle Classic and Paddle Billing, though we recommend you generate new keys when integrating with Paddle Billing.
Technical comparison
Where Paddle Classic is made up of a few different APIs, Paddle Billing is powered by one unified API. We prioritized consistency and conformity to REST standards when building the Paddle Billing API.
| Property | Classic | Billing |
|---|---|---|
| Base URL | vendors.paddle.com/api | api.paddle.com |
| Authentication | Passed in the body of a request | Bearer authentication |
| Versioning | URL versions; major/minor versions | Passed using a Paddle-Version header; major versions |
| Success responses | "success": "true" in the response body | 2xx response codes; data and meta in the response body |
| Error responses | "success": "false" in the response body | 4xx or 5xx response codes; error and meta in the response body |
| Deletion | Not possible | Not possible, but archiving supported across entities |
| Pagination | Not always present | Cursor-based pagination, with details in meta.pagination |
| IDs | Auto-incrementing IDs | Paddle IDs for all entities |
| Sideloading | Not possible | Return related entities using include query parameter |
| Empty values | May be omitted in responses | Returned in responses as null |
| Custom data | passthrough parameter; custom_data as stringified JSON for some endpoints | custom_data object across all core entities |
| Request bodies | application/x-www-form-urlencoded | application/json; requests closely mirror responses |
| Standard fields | No standardization | All entities return status, created_at, and updated_at fields |
| Rate limiting | Different limits across endpoints | Max 240 requests/minute; 429 response code returned |
Notifications (webhooks) are important for provisioning and order fulfillment. They're more robust in Paddle Billing, built around a centralized event stream.
| Property | Classic | Billing |
|---|---|---|
| Creation | Using Paddle dashboard | Using Paddle dashboard and the API |
| Max webhook endpoints | 5 | 10 active; no limit on inactive |
| Events available | 18 | 42 |
| Event subscriptions | Global | Endpoint specific |
| Payload | application/x-www-form-urlencoded; may include data not returned in the API | application/json; includes the new or changed entity in the Paddle API |
| Sensitive fields | Only sent to the primary endpoint | No concept of sensitive fields |
| Primary endpoint | Receives all fields, including sensitive fields | No concept of a primary endpoint |
| Logs | Using the Paddle dashboard; global only | Using Paddle dashboard and the API; global, endpoint specific, and for a specific notification |
| Webhook simulator | Lets you send test notifications using mock data | Lets you simulate single events and complex scenarios, like subscription creation, renewals, and cancellation |
| Event stream | Not available | Poll /events using the Paddle API |
| Failed delivery | Retried every 15 minutes over three days | Replayed using an exponential backoff schedule; may be replayed using the Paddle API |
| Product fulfillment | Paddle-led fulfillment by setting a webhook endpoint against products | Handle fulfillment using transaction webhooks |
| Signature verification | Signature in payload; requires PHP serialization | Paddle-Signature header; hash using SHA256 |
There's a new version of Paddle.js for Paddle Billing. Many concepts are the same, but it now supports multi-product checkouts and new ways to localize.
| Property | Classic | Billing |
|---|---|---|
| Version | 1 | 2 |
| CDN URL | https://cdn.paddle.com/paddle/paddle.js | https://cdn.paddle.com/paddle/v2/paddle.js |
| Include | Manually load by adding to <head> | Manually load by adding to <head>, or import using the Paddle.js wrapper |
| Initialization | Pass vendor ID to Paddle.Setup() | Pass client-side token to Paddle.Initialize() |
| Retain authentication | Pass a Retain API key to Paddle.Setup() | Automatically authenticated using client-side token |
| Work with Retain | Available using profitwell method | Available using Paddle.Retain methods |
| TypeScript support | Not available | Available using the Paddle.js wrapper |
| Callbacks | eventCallback, successCallback, and closeCallback | Single eventCallback |
| Update checkouts | Not possible | Dynamically update items and discounts on an opened checkout |
| Items | Single product checkouts only | Multi-product checkouts supported |
| Pricing pages | Paddle.Product.Prices() returns localized prices for one product | Paddle.PricePreview() returns localized prices for a list of prices |
| One-page checkout | Prefill required properties at checkout to land on the second page | Pass variant with the value one-page to present a one-page checkout experience |
Methods
Core methods are the same, with new parameters to support multi-product checkouts, new ways to localize, and ways to work with Paddle IDs.
| Classic | Billing |
|---|---|
Paddle.Setup() | Paddle.Initialize() |
Paddle.Setup() | Paddle.Update() |
Paddle.Environment.set() | Paddle.Environment.set() |
Paddle.Checkout.open() | Paddle.Checkout.open() |
Paddle.Checkout.updateCheckout() | |
Paddle.Checkout.updateItems() | |
Paddle.Checkout.close() | |
Paddle.Product.Prices() | Paddle.PricePreview() |
Paddle.Retain.demo() | |
Paddle.Retain.initCancellationFlow() | |
Paddle.Spinner.show() | Paddle.Spinner.show() |
Paddle.Spinner.hide() | Paddle.Spinner.hide() |
Paddle.Status.libraryVersion | Paddle.Status.libraryVersion |
Paddle.Audience | |
Paddle.Download | |
Paddle.Order | |
Paddle.User.History() |
Events
Events are simplified, with a standard event payload that you can compare across the checkout lifecycle.
| Classic | Billing |
|---|---|
Checkout.Loaded | checkout.loaded |
Checkout.Close | checkout.closed |
checkout.updated | |
Checkout.Complete | checkout.completed |
Checkout.Quantity.Change | checkout.items.updated |
checkout.items.removed | |
Checkout.Login | checkout.customer.created |
Checkout.Customer.Details | checkout.customer.updated |
Checkout.Logout | checkout.customer.removed |
Checkout.Payment.Selected | checkout.payment.selected |
checkout.payment.initiated | |
checkout.payment.failed | |
Checkout.Coupon.Applied | checkout.discount.applied |
Checkout.Coupon.Remove | checkout.discount.removed |
checkout.warning | |
Checkout.Error | checkout.error |
Checkout.Location.Submit | |
Checkout.Vat.Applied | |
Checkout.Vat.Remove | |
Checkout.PaymentComplete | |
Checkout.User.Subscribed | |
Checkout.Language.Change | |
Checkout.Vat.Add | |
Checkout.Vat.Cancel | |
Checkout.Vat.Submit | |
Checkout.WireTransfer.Complete | |
Checkout.OfflinePayment.DetailsComplete | |
Checkout.PaymentMethodChange | |
Checkout.WireTransfer.PaymentMethodChange |
Core entities
Customers in Paddle Billing are the people and businesses that make purchases. Customer entities store key information like name, email, and localization information. They have two subentities: addresses and businesses.
Key changes
| Property | Classic | Billing |
|---|---|---|
| Data structure | Customer data stored against subscription user | Customer, address, and business entities |
| Data access | Using Paddle dashboard; limited access using the API | Using Paddle dashboard and the API; all data may be updated by you |
| Tax and business information | Stored against subscription user | Stored against a related business entity; customers may have multiple businesses |
| Address information | Stored against subscription user | Stored against a related address entity; customers may have multiple addresses |
| Relation to subscriptions | One customer, one subscription | Customers may be linked to multiple subscriptions |
Customer entity
Customer entities in Paddle Billing hold top-level information about someone making a purchase.
The closest equivalent in Paddle Classic is a subscription user, though information about a subscription has moved to a new subscription entity.
| Classic | Billing |
|---|---|
user.user_id | customer.id |
customer.name | |
user.user_email | customer.email |
user.marketing_consent | customer.marketing_consent |
customer.status | |
customer.custom_data | |
customer.locale | |
customer.created_at | |
customer.updated_at | |
customer.import_meta | |
user.subscription_id | |
user.plan_id | |
user.state | |
user.signup_date | |
user.last_payment | |
user.next_payment |
Address entity
Address is a new entity in Paddle Billing. It holds information about a billing address for a customer.
There's no equivalent in Paddle Classic.
| Classic | Billing |
|---|---|
address.id | |
address.description | |
address.first_line | |
address.second_line | |
address.city | |
address.postal_code | |
address.region | |
address.country_code | |
address.custom_data | |
address.status | |
address.created_at | |
address.updated_at | |
address.import_meta |
Business entity
Business is a new entity in Paddle Billing. It holds information about a business for a customer.
There's no equivalent in Paddle Classic.
| Classic | Billing |
|---|---|
business.id | |
business.name | |
business.company_number | |
business.tax_identifier | |
business.status | |
business.contacts[] | |
business.created_at | |
business.updated_at | |
business.custom_data | |
business.import_meta |
Your catalog in Paddle Billing is made up of products, prices, and discounts. Products describe the items customers can purchase, and prices describe how much and how often a product is charged.
Key changes
| Property | Classic | Billing |
|---|---|---|
| Data structure | Product (one-time) and plan (recurring) entities | Product and related price entities |
| Data access | Using Paddle dashboard; limited access using the API | Using Paddle dashboard and the API; all data may be updated by you |
| Fulfillment | License keys and product downloads handled by Paddle | Build your own workflows using transaction webhooks |
| Price localization | Set currency-specific prices for a currency against an item | System-wide automatic currency conversion; set country-specific prices for an item |
| Relation to subscriptions | One item per subscription | Multi-item subscriptions |
| Non-catalog items | Using pay links | Passing product and price attributes to a transaction or subscription |
| Discount types | Percentage or flat fee | Percentage, flat fee, or flat fee per unit |
| Discount coupon codes | Required | Optional |
Product entity
Product entities in Paddle Billing describe an item that customers can purchase. They don't hold information about a charge, which is held against related price entities.
Products are comparable to products in Paddle Classic, but there's no distinction between one-time and recurring products in Paddle Billing.
| Classic | Billing |
|---|---|
product.id | product.id |
product.name | product.name |
product.tax_category | |
product.type | |
product.description | product.description |
product.icon | product.image_url |
product.custom_data | |
product.status | |
product.import_meta | |
product.created_at | |
product.updated_at | |
product.base_price | |
product.currency | |
product.sale_price | |
product.screenshots |
Price entity
Price is a new entity in Paddle Billing. Prices describe how products are charged.
In Paddle Classic, recurring price information is set against the subscription plan. In Paddle Billing, prices may be one-time as well as recurring.
| Classic | Billing |
|---|---|
plan.id | price.id |
price.product_id | |
price.description | |
price.type | |
price.name | |
plan.billing_type, plan.billing_period | price.billing_cycle |
plan.trial_days | price.trial_period |
price.tax_mode | |
plan.recurring_price | price.unit_price |
price.unit_price_overrides[] | |
price.status | |
price.custom_data | |
price.import_meta | |
price.created_at | |
price.updated_at | |
plan.initial_price |
Discount entity
Discounts in Paddle Billing let you reduce the amount a customer has to pay. They're applied to transactions and subscriptions.
They're comparable to coupons or modifiers in Paddle Classic.
There's no one-to-one entity for modifiers in Paddle Billing. You can create multiple prices for a product to offer it at different price points, or you create discounts to reduce the amount a customer has to pay by a percentage or flat fee.
| Classic | Billing |
|---|---|
discount.id | |
discount.status | |
coupon.description | discount.description |
discount.enabled_for_checkout | |
coupon.coupon | discount.code |
coupon.discount_type | discount.type |
coupon.discount_amount | discount.amount |
coupon.discount_currency | discount.currency_code |
coupon.is_recurring | discount.recur |
discount.maximum_recurring_intervals | |
coupon.allowed_uses | discount.usage_limit |
coupon.product_id | discount.restrict_to |
coupon.expires | discount.expires_at |
discount.custom_data | |
coupon.times_used | discount.times_used |
discount.created_at | |
discount.updated_at | |
discount.import_meta |
All revenue in Paddle Billing flows through transactions. They calculate and capture revenue for checkouts, invoices, and subscriptions. Every payment attempt in Paddle Billing has a related transaction entity.
You may create transactions yourself to collect for a charge, passing it to Paddle.js to open a checkout or letting Paddle send an invoice for manual collection. Paddle automatically creates transactions for new checkouts, subscription renewals, and to bill for changes or one-time charges for subscriptions.
Key changes
| Property | Classic | Billing |
|---|---|---|
| Data structure | Orders and transactions (one-time); subscriptions and charges (recurring) | Transactions and related subscriptions |
| Data access | Using Paddle dashboard and the API | Using Paddle dashboard and the API |
| Invoicing | Using separate invoice module | Manually-collected transactions and subscriptions |
| Subscription collection options | Automatic, using a saved payment method or Paddle Checkout | Automatic, using a saved payment method or Paddle Checkout; or manual, by sending an invoice |
| Relation to customers | One customer, one subscription | Customers may have multiple subscriptions |
| Items | Single product subscriptions only | Multi-product subscriptions supported |
| Non-catalog items | Not supported | Bill for items that aren't in your catalog |
| Supported subscription workflows | Pause/resume, cancel, upgrade/downgrade, change payment method, change billing date | Pause/resume, cancel, upgrade/downgrade, change billing date, change payment method, change currency, transition to billing by invoice |
| Integration journeys | Build subscription workflows using the Paddle API | Build subscription workflows using the Paddle API; generate secure customer portal links to handle subscription workflows |
| Payments | Stored against transactions (one-time), or subscriptions (recurring) | Stored against a transaction |
| Saved payment methods | Not a standalone entity | Standalone entity you can work with using the API |
| Paddle Retain | Payment Recovery | Payment Recovery, Cancellation Flows, Term Optimization |
Subscription entity
Subscriptions in Paddle Billing describe a recurring billing relationship with a customer.
They bring together what was previously on a subscription user and a subscription plan in Paddle Classic.
| Classic | Billing |
|---|---|
user.subscription_id | subscription.id |
user.state | subscription.status |
plan.user_id | subscription.customer_id |
subscription.address_id | |
subscription.business_id | |
user.next_payment.currency | subscription.currency_code |
subscription.created_at | |
subscription.updated_at | |
user.signup_date | subscription.started_at |
subscription.first_billed_at | |
user.next_payment.date | subscription.next_billed_at |
user.paused_at | subscription.paused_at |
subscription.canceled_at | |
subscription.discount | |
subscription.collection_mode | |
subscription.billing_details | |
user.last_payment.date, user.next_payment.date | subscription.current_billing_period |
plan.billing_type, plan.billing_period | subscription.billing_cycle |
user.paused_from | subscription.scheduled_change |
user.update_url, user.cancel_url | subscription.management_urls |
plan.plan, user.plan_id | subscription.items[] |
user.passthrough | subscription.custom_data |
subscription.import_meta | |
user.next_payment | subscription.next_transaction |
Transaction entity
Transactions in Paddle Billing tie together products, prices, and discounts with customers to calculate revenue for checkouts, invoices, and subscriptions. Every payment attempt in Paddle Billing has a related transaction entity.
They're most similar to orders in Paddle Classic, but contain elements of payments too.
| Classic | Billing |
|---|---|
order.order.order_id, order.order.subscription_order_id | transaction.id |
order.state, payment.is_paid | transaction.status |
order.order.customer | transaction.customer_id |
transaction.address_id | |
transaction.business_id | |
passthrough | transaction.custom_data |
order.order.order_currency | transaction.currency_code |
payment.is_one_off_charge | transaction.origin |
order.order.is_subscription, order.order.subscription_id | transaction.subscription_id |
transaction.invoice_number | |
transaction.collection_mode | |
order.order.coupon_code | transaction.discount_id |
transaction.billing_details | |
transaction.billing_period | |
transaction.items[] | |
order.order.total, order.order.total_tax, order.order.quantity | transaction.details |
order.order.completed, payment | transaction.payments[] |
order.checkout | transaction.checkout |
transaction.created_at | |
transaction.updated_at | |
transaction.billed_at | |
order.order.has_locker, order.lockers | |
order.order.formatted_total, order.order.formatted_tax | |
order.order.customer_success_redirect_url | |
order.order.receipt_url, payment.receipt_url | |
payment.payout_date |
Customer portal session entities
Customer portal session is a new entity in Paddle Billing. You can create a customer portal session to generate authenticated links to the customer portal, letting customers manage their subscriptions, payments, and account information.
You can link to the customer portal to add core subscription management, billing information, and payment history to your app.
There's no equivalent in Paddle Classic.
| Classic | Billing |
|---|---|
portal.id | |
portal.customer_id | |
user.update_url, user.cancel_url | portal.urls |
portal.created_at |