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 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

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

Webhooks

	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 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

Paddle.js

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 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.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 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

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`
	`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`

Product catalog

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
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 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`
`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`

Billing and subscriptions

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	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`
	`portal.urls`
	`portal.created_at`

Next steps

Paddle Classic to Paddle Billing: Migration checklist

Paddle Classic to Paddle Billing: Feature comparison

Sign up to get notified when our API evolves