Everything you need to do to migrate from Paddle Classic to Paddle Billing.
Ready to start your migration from Paddle Classic to Paddle Billing? This guide walks through all the steps that you need to set up Paddle Billing, build an integration, and prepare for go-live.
Porting subscription data from Paddle Classic to Paddle Billing is in early access.
As part of migration, you'll need to build an integration with Paddle Billing, then run it alongside your integration with Paddle Classic while we port your subscription data over from Classic to Billing. You should be prepared to run two integrations for a little while.
Before starting your migration, check that you're eligible. We support porting subscription data from Paddle Classic where:
You have fewer than 50,000 active subscriptions in your live account in total
You have a straightforward product catalog, for example: a single plan, good-better-best plans, or seat-based pricing
You don't rely heavily on modifiers as part of your workflows
If you have more than 50,000 subscriptions in total or have a complex product catalog, we're not ready to port your data over just yet, but we'd love to hear from you. We're keen to understand how you model your prices and learn more about your subscribers, so we can help you migrate in the future. Contact us at sellers@paddle.com.
Turn on Paddle Billing for your account, review shared settings, then configure new localization settings. Your Paddle account is already verified, so you don't need to do this again.
Add products to your product catalog
Add subscription plans, recurring addons, one-off charges, and other items that you sell to Paddle Billing.
Integrate with your frontend
Integrate Paddle with your frontend using Paddle.js v2.
Handle subscription lifecycle events
Subscribe to webhooks, then build workflows to handle subscription lifecycle events, like signing up, pausing, or canceling.
Start running transactions through Paddle Billing
Route new customers to your Paddle Billing checkout and workflows, while maintaining your existing Paddle Classic workflows for existing subscriptions.
Request Paddle Classic subscription data migration
Contact the Paddle team to request a subscription data migration. We'll port your Paddle Classic subscription data to Paddle Billing.
Remove your Paddle Classic integration
Once your data is migrated, you can turn off your Paddle Classic integration entirely.
Most settings are shared between Paddle Classic and Paddle Billing. This includes payment methods, checkout branding options, business settings and team members, taxable categories, and payout settings. You don't need to go through account verification again.
We've improved localization and added more flexibility to Paddle Checkout, so there are some settings to review.
Activate Paddle Billing
Turn on Paddle Billing for your account to get access to the new API, webhooks, and pages in the Paddle web app. Paddle creates a new set of data for Paddle Billing that's separate to your Paddle Classic data.
Go to Business Account > Account Settings > Get Paddle Billing to activate Paddle Billing.
You can switch between Paddle Classic and Paddle Billing in the Paddle web app using the toggle at the bottom-right.
Set default payment link
Paddle Billing can automatically generate a payment link for any transaction. It's a quick way to open Paddle Checkout for a transaction. It should be a page that includes Paddle.js, typically your checkout page.
Go to Paddle > Checkout > Checkout settings, then add a default payment link.
Set this to domain that you've verified for use on Paddle. You can always change this later.
Paddle Billing can automatically convert prices into the best currency for a location at checkout. Choose the currencies you'd like to turn on automatic conversion for.
Later, you can add country-specific overrides to prices to manually override base prices with custom prices for countries that you choose.
Go to Paddle > Business account > Currencies to choose which currencies you'd like Paddle to automatically convert.
API keys for Paddle Classic work with Paddle Billing, but we recommend generating new keys and familiarizing yourself with authentication before getting started.
Go to Paddle > Developer tools > Authentication to generate API keys.
Send a request to the /event-types endpoint to test your authentication.
Your product catalog contains the items that you sell to your customers. This includes subscription plans, recurring addons, and one-off items.
Paddle Billing offers a more flexible way of structuring your product catalog, and includes support for multi-product subscriptions. This is a great chance to review how your prices are modeled.
Want a thorough audit of your pricing? Our Price Intelligently experts can help you unlock 25-50% higher growth rates, with insights from over 50,000 subscription businesses.
Create products and prices
Products describe the items that you sell. They have related prices that describe how you charge for them. Add products and prices to Paddle for your subscription plans, recurring addons, and one-off items.
Go to Paddle > Catalog > Products to start adding products and prices.
Discounts let you reduce the amount a customer has to pay by a percentage or fixed amount. They can be one-time or recurring, and apply to an entire transaction or just items that you choose.
Go to Paddle > Catalog > Discounts to start adding discounts.
Paddle Billing comes with a new version of Paddle Checkout, designed to handle securely capturing card details or payment using another payment method when customers sign up, change their payment details, or want to pay invoices by card or other payment method.
You cannot include Paddle.js v1 and Paddle.js v2 on the same page. We recommend creating new pages for your Paddle Billing checkout and frontend workflows.
Generate client-side tokens
Paddle.js uses client-side tokens for authentication. You use a client-side token when including and initializing Paddle.js, rather than passing your seller ID.
Go to Paddle > Developer tools > Authentication to generate a new client-side token.
Initialize Paddle.js by passing the token parameter passed to Paddle.Initialize() in your frontend.
Paddle.js v2 works in a similar way to Paddle.js v1, but includes new parameters for Paddle.Initialize() (previously Paddle.Setup()) and Paddle.Checkout.open(), new methods for dynamically updating opened checkouts, and new events. The CDN link to include Paddle.js v2 is different to Paddle.js v1.
Swap authentication for a client-side token, pass an array of items to your open checkout function, and update event callbacks.
Paddle Billing introduces a new Paddle.PricePreview() method that you can use to get localized pricing for multiple products for a given location — including discount calculations.
Swap Paddle.Product.Prices() calls for Paddle.PricePreview() in your pricing page.
Update your default payment link, or build a default payment link page
Your default payment link is a quick way to open Paddle Checkout for a transaction. You can set this to the checkout page that you built, or create another page that includes Paddle.js.
If you'd like your default payment link page to be different from your checkout page, build a new page that includes Paddle.js.
Go to Paddle > Checkout > Checkout settings then update your default payment link.
Paddle.js v2 integrates with Retain, so you don't have to include a separate Retain script. Client-side tokens for live accounts authenticate with both Paddle Billing and Paddle Retain, too.
Update Paddle.Initialize() calls to include pwCustomer, passing either the Paddle ID or email address of a customer.
In your backend, update workflows that handle subscription lifecycle events, like when customers sign up, upgrade or downgrade, or pause or cancel their subscription. You can use our SDKs to speed up the process.
The Paddle Billing API gives you more access to your data, and includes a new subscription entity that you can map to a subscription record in your database. We designed operations in our API and methods in our SDKs to closely match subscription scenarios, so working with Paddle Billing should be more intuitive than Classic.
As part of the migration process, you'll need to run Paddle Classic and Paddle Billing alongside each other for a short while. We recommend building your workflows in a way that means you can easily remove your Paddle Classic logic after migration is completed.
Create notification destinations
Create notification destinations to tell Paddle where to deliver webhook notifications and which events you'd like to receive notifications for. There's no primary endpoint in Paddle Billing.
Go to Paddle Developer tools > Notifications to start creating notification destinations.
Customers need a way to change the payment method that they use to pay for subscription renewals and charges. This is important where subscriptions are past due.
Emails from Paddle include a link that customers may use to update their payment method.
Build a workflow to let customers update their payment details using Paddle.js and the Paddle API.
Paddle Billing supports multi-product subscriptions, meaning upgrades and downgrades can happen in more scenarios.
If you offer multiple plans, you should provide a way for customers to upgrade or downgrade their subscription. You might also sell addons, like additional users or modules, that you should let customers add or remove.
Build a workflow to let customers upgrade or downgrade, and add or remove any recurring items.
Start processing new subscriptions through Paddle Billing
Update your app so that you process new subscriptions through your Paddle Billing integration. You still should handle changes to existing subscriptions using your Paddle Classic logic.
Make code changes in your frontend and backend so that new subscriptions are managed through Paddle Billing.
6. Migrate Classic subscription data to Billing
Now you're running through Paddle Billing, request a migration to port your Paddle Classic subscriptions and customers to Paddle Billing. The aim of migration is to move all of your subscriptions to Paddle Billing, so you can turn off your Paddle Classic integration.
Porting subscription data from Paddle Classic to Paddle Billing is in early access. We may not be able to accept everyone in to the early access program.
You should build an integration with Paddle Billing before requesting a migration. This is not part of the process.
Handle imported entities
When customers, addresses, businesses, and subscriptions are migrated, imported events occur in Paddle Billing. We recommend building logic to update subscription records in your database when they've been imported.
Create a notification destination for subscription.imported and other imported events. Make changes to records in your database when they've been imported so that they use the workflows you built for Paddle Billing. We recommend storing the new customer ID and subscription ID for each subscription.
Request Paddle Classic subscription data migration
Contact the Paddle Seller Support team to request that we migrate your subscription data from Paddle Classic to Paddle Billing. We'll port your subscription, customer, and other data from Paddle Classic to Paddle Billing. Historic reporting data remains on Paddle Classic.
Once you've completed the steps above and heard from Paddle that your data has been migrated, you're live with Paddle Billing — congratulations! You can safely turn off your Paddle Classic integration.
We recommend keeping up-to-date with changes to the Paddle platform.
Turn off your Paddle Classic integration
Now you've fully migrated to Paddle Billing, you can safely remove any Paddle Classic logic from your frontend and backend. You'll still have access to your Paddle Classic data in the Paddle web app for historic reporting.
Remove Paddle Classic logic from your app.
Sign up for developer changelog updates
We add features to Paddle Billing regularly. We recommend that you check our changelog regularly or sign up for emails to get updates about new features and changes.
Check our developer changelog and use the email form to sign up for updates.
Paddle Billing integrates with Retain Cancellation Flows and Term Optimization, proactively reducing churn and maximizing customer lifetime value. Retain works with Paddle.js, so you don't need to include an additional script to get started.
With Paddle Billing, you can localize for countries and not just currencies — great for countries or regions that share a currency (like the euro) where willingness-to-pay and purchasing power may different.
Paddle.js v2 includes new ways to work with localized prices, and lets you dynamically update opened checkouts. If you implemented a checkout that mirrored your Paddle Classic integration, you may like to build a more integrated experience using our new methods and events.
