For AI agents and LLMs: a structured documentation index is available at /llms.txt. Every page has a Markdown sibling — append .md to any URL.

Skip to content
Docs

Plan your migration from Paddle Classic to Paddle Billing

Learn how a migration from Paddle Classic to Paddle Billing works at a high level, and get key information about what you need to know before you migrate.

AI summary

A high-level migration plan from Paddle Classic to Paddle Billing, covering catalog setup, frontend integration, fulfillment, subscription workflows, live transactions, data porting, and Classic integration removal.

  • • Your Paddle Classic integration continues to work throughout the migration — you can build and test Paddle Billing in parallel without disrupting existing customers.
  • • The migration is sequential: build the full Paddle Billing integration first, start routing new transactions through it, port subscription data, then remove Classic.
  • • Use the dashboard migration screens to port subscription data from Classic to Billing — customers, plans mapped to prices, and active subscriptions are all migrated together.

After you activate Paddle Billing for your account, your Paddle Classic integration continues to work as before. To move to Paddle Billing, you need to build an integration with our new platform and migrate your Classic data.

This guide helps you plan how to move from Paddle Classic to Paddle Billing. It provides high level steps that walk through what you need to consider and do before you migrate.

What are you migrating?

Pick all that apply — content updates to match.

Your migration plan

Activate Paddle Billing

Turn on Paddle Billing for your account to get access to the new API, webhooks, and pages in the Paddle dashboard. 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.

  • When you turn on Paddle Billing, your existing integration continues to work as before. Customers can continue to buy items using your existing integration.
  • Existing customer and subscription data isn't ported automatically or changed in any way. Any subscriptions created using your Paddle Classic integration are created in Paddle Classic as before.
  • You can switch between Paddle Classic and Paddle Billing in the Paddle dashboard using the toggle at the bottom-left.

Build your product catalog

Create products and prices in Paddle to describe the items that you offer. Products describe the items that you offer, and related prices describe how much and how often they're billed.

Toggle Paddle Billing, then go to Paddle > Products to start creating products and prices. You can also use the API.

  • If you use invoices in Paddle Classic, any products you created already exist in Paddle Billing. You'll need to create new prices.
  • If you plan to import subscriptions, you can map plans in Paddle Classic to products in Paddle Billing as part of the migration process. We'll create new prices for the products due to the complexity of the data. This doesn't impact the customer experience.
  • Currency price overrides in Paddle Classic don't have a direct equivalent in Paddle Billing. We recommend turning on automatic currency conversion, then adding country-specific prices to prices for your core markets later.

Integrate with your frontend

Paddle Billing comes with a new version of Paddle.js, designed to handle securely capturing payment details when customers signup or make a purchase, change their payment details, or want to pay invoices by card or other payment method.

Update your pricing page and checkout to use Paddle.js v2, which has new and updated methods and events.

  • Invoices can be paid using a checkout link in Paddle Billing, so you need to complete this step even if you only bill by invoice. You don't need to build a complete checkout in this case — just include and initialize Paddle.js on a page on your website, then set it as your default payment link.
  • You can install Paddle.js v2 using a package manager and work with TypeScript definitions using the Paddle.js wrapper.
  • Paddle.js supports multi-product checkouts, so there's no need to create bundle products.
  • If you offer one-time products and often get repeat customers, consider letting customers sign up for accounts on your website so they can save payment methods for future purchases.
  • To create pay links, create a transaction and pass the transaction ID to Paddle.js to open a checkout. Transaction checkouts are hosted on your website, rather than Paddle.com.

Handle fulfillment

When a customer completes a purchase, you need to handle fulfillment. Paddle Billing includes webhooks, a unified event stream, and comprehensive documentation that you can use to build your own fulfillment workflows.

Build or update post-purchase and fulfillment workflows to use webhooks in Paddle Billing.

  • Invoices in Paddle Billing are transactions where the collection mode is manual. If you used invoice webhooks for fulfillment in Paddle Classic, use transaction webhooks in Paddle Billing.
  • Product delivery and license key generation aren't handled by Paddle in Paddle Billing. We recommend building this functionality yourself.
  • You can use the customer portal to let customers grab invoices and revise invoice details.
  • If you offer subscriptions, we recommend creating new tables in your database to hold Paddle Billing subscriptions rather than enriching existing subscription records.

Build subscription lifecycle workflows

Customers need a way to make changes to their subscription, including canceling, upgrading and downgrading, or changing their billing details. Paddle Billing comes with more ways to manage subscriptions using the API, and the customer portal that you can integrate instead of building workflows yourself.

Build or update workflows for subscription lifecycle events, like letting customers upgrade or downgrade, pause or resume, or cancel their subscription.

  • 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.
  • Paddle Billing has four SDKs that you can use, as well as a Next.js starter kit that includes core billing management.
  • You can integrate the customer portal to let customers cancel their subscription and update their payment details.
  • You can use webhook simulator to simulate complex scenarios, like new signups and dunning workflows.

Start transacting through Paddle Billing

When you're ready, start transacting using Paddle Billing. This means that you run customers through your Paddle Billing checkout, or use the invoicing functionality in Paddle Billing.

  • If you create and issue invoices using Paddle Billing, the invoice numbering sequence carries over from Paddle Classic. This means you can maintain sequential and gapless numbering, required for compliance.
  • For invoicing, customers, addresses, and businesses are shared between Paddle Classic and Paddle Billing.
  • Reporting is separate between Paddle Classic and Paddle Billing. Historic reporting data isn't ported and remains in Classic. You can always switch to Paddle Classic using the toggle to work with your historic data.
  • If you want to port subscription data to Paddle Billing, you'll need to have at least one completed transaction to start the process. You should create and manage new subscriptions using Paddle Billing, while running existing subscriptions through Paddle Classic.

Port subscription data to Billing

Once you're transacting through Paddle Billing, you can port your subscription data from Paddle Classic.

Use the migration screens in the dashboard to map your product catalog and port customers and subscriptions. Webhooks occur when subscriptions are migrated, so you can update records in your database and route customers to the correct workflows.

  • You can only start a migration once you've fully set up your Paddle Billing integration and have at least one completed transaction.
  • You can choose which subscriptions you want to migrate as part of the process. We recommend starting with a small number first.
  • When subscriptions are ported, they're canceled in Paddle Classic and imported into Paddle Billing. subscription.imported occurs in Paddle Billing so you can update your records.
  • As part of porting your data, imported events occur in place of created events in Paddle Billing. For example, subscription.imported occurs instead of subscription.created.
  • You can export a list of subscriptions after a migration is completed, then use this list to update your database records instead of listening for webhooks.
  • The process is seamless for customers. They're not notified that their subscription has been canceled and imported, and subscriptions renew as normal with no disruption.
  • Only active subscriptions can be migrated. You can migrate past due subscriptions after dunning when their account is in good standing.

Remove your Paddle Classic integration

You're done. You can remove Paddle Classic from your stack and use Paddle Billing.

  • If you have past due subscriptions that can't be migrated, you can follow up your initial migration with another migration to port those when they're in good standing or have canceled.
  • You can switch to Paddle Classic to get access to your historic data and reports.

Integrate with Paddle Retain — live only

Paddle Billing integrates with Paddle Retain, an all-in-one solution that combines world-class subscription expertise with algorithms that use billions of datapoints to recover failed payments, reduce churn, and automatically increase customer lifetime value (LTV).

Integrate Payment Recovery, Cancellation Flows, and Term Optimization to proactively reduce churn and maximize customer lifetime value.

  • Paddle Retain powers dunning and payment recovery in Paddle Billing.
  • Turn on and set up Payment Recovery in Paddle Retain to customize failed payment retries and determine what happens when dunning is exhausted.
  • If you don't turn on Payment Recovery in Paddle Retain, Paddle Billing automatically retries payment for failed subscription renewals, but doesn't email customers.
  • If you used Payment Recovery with Paddle Classic, you don't need to do anything. We'll use the same settings.
  • Retain works with Paddle.js v2, so you don't need to include an additional script.

Was this page helpful?