Technical data mapping between Paddle Classic and Paddle Billing
All the data in Paddle Classic can be mapped to Paddle Billing, but as a complete reimagining of how you work with the Paddle platform, some of the data doesn't map one-to-one.
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.
| Classic | Billing | |
|---|---|---|
| Base URL | vendors.paddle.com/api Tooltip | api.paddle.com Tooltip |
| 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 Tooltip |
| Deletion | Not possible | Not possible, but archiving supported across entities Tooltip |
| Pagination | Not always present | Cursor-based pagination, with details in meta.pagination |
| IDs | Auto-incrementing IDs | Paddle IDs for all entities Tooltip |
| 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 Tooltip |
Notifications (webhooks) are important for provisioning and order fulfillment. They're more robust in Paddle Billing, built around a centralized event stream.
| 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 Tooltip | Endpoint specific Tooltip |
| 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 Tooltip |
| Primary endpoint | Receives all fields, including sensitive fields | No concept of a primary endpoint Tooltip |
| 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 Tooltip |
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.
| 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 Tooltip |
| 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 Tooltip | Single eventCallback Tooltip |
| 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 Tooltip |
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.Initalize() |
Paddle.Setup() | Paddle.Update() Tooltip |
Paddle.Environment.set() | Paddle.Environment.set() |
Paddle.Checkout.open() | Paddle.Checkout.open() Tooltip |
Paddle.Checkout.updateCheckout() Tooltip | |
Paddle.Checkout.updateItems() Tooltip | |
Paddle.Checkout.close() | |
Paddle.Product.Prices() | Paddle.PricePreview() Tooltip |
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 Tooltip | |
Paddle.Download Tooltip | |
Paddle.Order Tooltip | |
Paddle.User.History() Tooltip |
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 Tooltip |
checkout.updated | |
Checkout.Complete | checkout.completed Tooltip |
Checkout.Quantity.Change | checkout.items.updated Tooltip |
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 Tooltip | |
Checkout.Coupon.Applied | checkout.discount.applied |
Checkout.Coupon.Remove | checkout.discount.removed |
checkout.warning Tooltip | |
Checkout.Error | checkout.error Tooltip |
Checkout.Location.Submit Tooltip | |
Checkout.Vat.Applied Tooltip | |
Checkout.Vat.Remove Tooltip | |
Checkout.PaymentComplete Tooltip | |
Checkout.User.Subscribed Tooltip | |
Checkout.Language.Change | |
Checkout.Vat.Add | |
Checkout.Vat.Cancel | |
Checkout.Vat.Submit | |
Checkout.WireTransfer.Complete Tooltip | |
Checkout.OfflinePayment.DetailsComplete Tooltip | |
Checkout.PaymentMethodChange Tooltip | |
Checkout.WireTransfer.PaymentMethodChange Tooltip |
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
| 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 Tooltip |
customer.name | |
user.user_email | customer.email |
user.marketing_consent Tooltip | customer.marketing_consent |
customer.status Tooltip | |
customer.custom_data | |
customer.locale | |
customer.created_at | |
customer.updated_at | |
customer.import_meta | |
user.subscription_id Tooltip | |
user.plan_id Tooltip | |
user.state Tooltip | |
user.signup_date Tooltip | |
user.last_payment Tooltip | |
user.next_payment Tooltip |
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 Tooltip | |
address.description | |
address.first_line | |
address.second_line | |
address.city | |
address.postal_code | |
address.region | |
address.country_code | |
address.custom_data | |
address.status Tooltip | |
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 Tooltip | |
business.name | |
business.company_number | |
business.tax_identifier | |
business.status Tooltip | |
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
| 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 | Licence 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 describes 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 Tooltip |
product.name | product.name |
product.tax_category | |
product.type | |
product.description | product.description |
product.icon | product.image_url |
product.custom_data | |
product.status Tooltip | |
product.import_meta | |
product.created_at | |
product.updated_at | |
product.base_price Tooltip | |
product.currency Tooltip | |
product.sale_price Tooltip | |
product.screenshots Tooltip |
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 Tooltip |
price.product_id Tooltip | |
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[] Tooltip | |
price.status Tooltip | |
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 Tooltip | |
discount.status Tooltip | |
coupon.description | discount.description |
discount.enabled_for_checkout Tooltip | |
coupon.coupon | discount.code Tooltip |
coupon.discount_type | discount.type Tooltip |
coupon.discount_amount | discount.amount |
coupon.discount_currency | discount.currency_code |
coupon.is_recurring | discount.recur |
discount.maximum_recurring_intervals Tooltip | |
coupon.allowed_uses | discount.usage_limit |
coupon.product_id | discount.restrict_to Tooltip |
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
| 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 Tooltip | 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 Tooltip |
| 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 Tooltip |
user.state | subscription.status Tooltip |
plan.user_id | subscription.customer_id |
subscription.address_id | |
subscription.business_id | |
user.next_payment.currency | subscription.currency_code Tooltip |
subscription.created_at | |
subscription.updated_at | |
user.signup_date | subscription.started_at |
subscription.first_billed_at Tooltip | |
user.next_payment.date | subscription.next_billed_at Tooltip |
user.paused_at | subscription.paused_at |
subscription.canceled_at | |
subscription.discount Tooltip | |
subscription.collection_mode Tooltip | |
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 Tooltip |
user.update_url, user.cancel_url | subscription.management_urls Tooltip |
plan.plan, user.plan_id | subscription.items[] Tooltip |
user.passthrough | subscription.custom_data |
subscription.import_meta | |
user.next_payment | subscription.next_transaction Tooltip |
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 Tooltip |
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 Tooltip |
order.order.is_subscription, order.order.subscription_id | transaction.subscription_id |
transaction.invoice_number | |
transaction.collection_mode Tooltip | |
order.order.coupon_code | transaction.discount_id |
transaction.billing_details | |
transaction.billing_period | |
transaction.items[] Tooltip | |
order.order.total, order.order.total_tax, order.order.quantity | transaction.details Tooltip |
order.order.completed, payment | transaction.payments[] Tooltip |
order.checkout | transaction.checkout |
transaction.created_at | |
transaction.updated_at | |
transaction.billed_at | |
order.order.has_locker, order.lockers Tooltip | |
order.order.formatted_total, order.order.formatted_tax | |
order.order.customer_success_redirect_url Tooltip | |
order.order.receipt_url, payment.receipt_url Tooltip | |
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 Tooltip | |
portal.customer_id | |
user.update_url, user.cancel_url | portal.urls Tooltip |
portal.created_at |