Data mapping: 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.
Porting subscription data from Paddle Classic to Paddle Billing is in early access.
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 sell 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 the Paddle Billing API.
Technical comparison
Where Paddle Classic was 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 | 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.
| Classic | Billing | |
|---|---|---|
| Creation | Via Paddle web app | Via Paddle web app 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 | Via the Paddle web app; global only | Via Paddle web app and the API; global, endpoint specific, and for a specific notification |
| Webhook simulator | Lets you send test notifications using mock data | Not available |
| Event stream | Not available | Poll /events via 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 fulfilment | Paddle-led fulfilment by setting a webhook endpoint against products | Handle fulfilment 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.
| 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 products |
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() |
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 have been simplified significantly, 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 you sell products to. Customer entities store key information like name, email, and localization information. They have two sub-entities: addresses and businesses.
Key changes
| Classic | Billing | |
|---|---|---|
| Data structure | Customer data stored against subscription user | Customer, address, and business entities |
| Data access | Via Paddle web app; limited access via the API | Via Paddle web app 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 you're billing through Paddle.
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 is 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 is 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 product catalog in Paddle Billing is made up of products, prices, and discounts. Products describe an item that you sell using Paddle, and prices describe how much and how often you charge for a product.
Key changes
| Classic | Billing | |
|---|---|---|
| Data structure | Product (one-time) and plan (recurring) entities | Product and related price entities |
| Data access | Via Paddle web app; limited access via the API | Via Paddle web app and the API; all data may be updated by you |
| Fulfilment | 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 |
| 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 you sell through Paddle. 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 is 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 you charge for products.
In Paddle Classic, recurring price information is usually 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
| Classic | Billing | |
|---|---|---|
| Data structure | Orders and transactions (one-time); subscriptions and charges (recurring) | Transactions and related subscriptions |
| Data access | Via Paddle web app and the API | Via Paddle web app 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 |
| Payments | Stored against transactions (one-time), or subscriptions (recurring) | Stored against a transaction |
| 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 |
