> For the complete documentation index, see [llms.txt](https://developer.paddle.com/llms.txt).

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

---

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.

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

{% collapsible title="Good to know" id="activate" %}

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

{% /collapsible %}

### Build your product catalog

[Create products and prices](https://developer.paddle.com/build/products/create-products-prices.md) 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.

{% callout type="note" %}
Use the [Paddle MCP server](https://github.com/PaddleHQ/paddle-mcp-server/) to use an AI assistant or AI-powered IDE to create your product catalog.
{% /callout %}

{% collapsible title="Good to know" id="catalog" %}

- 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](https://developer.paddle.com/build/products/offer-localized-pricing.md) to prices for your core markets later.

{% /collapsible %}

### Integrate with your frontend

Paddle Billing comes with [a new version of Paddle.js](https://developer.paddle.com/paddle-js/overview.md), 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.

{% callout type="note" %}
You can install Paddle.js v2 using a package manager and work with TypeScript definitions using [the Paddle.js wrapper](https://github.com/PaddleHQ/paddle-js-wrapper/).
{% /callout %}

{% collapsible title="Good to know" id="frontend" %}

- 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](https://developer.paddle.com/build/transactions/default-payment-link.md).
- You can install Paddle.js v2 using a package manager and work with TypeScript definitions using [the Paddle.js wrapper](https://github.com/PaddleHQ/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](https://developer.paddle.com/build/checkout/saved-payment-methods.md).
- To create pay links, [create a transaction](https://developer.paddle.com/build/transactions/create-transaction.md) and pass the transaction ID to Paddle.js to open a checkout. Transaction checkouts are hosted on your website, rather than Paddle.com.

{% /collapsible %}

### Handle fulfillment

When a customer completes a purchase, you need to handle fulfillment. Paddle Billing includes [webhooks](https://developer.paddle.com/webhooks/overview.md), a [unified event stream](https://developer.paddle.com/api-reference/events/overview.md), 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.

{% collapsible title="Good to know" id="fulfillment" %}

- [Invoices](https://developer.paddle.com/build/invoices/create-issue-invoices.md) in Paddle Billing are transactions where the collection mode is manual. If you used invoice webhooks for fulfillment in Paddle Classic, use [transaction webhooks](https://developer.paddle.com/webhooks/transactions/transaction-completed.md) 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](https://developer.paddle.com/concepts/customer-portal.md) 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.

{% /collapsible %}

### 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](https://developer.paddle.com/concepts/customer-portal.md) 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.

{% collapsible title="Good to know" id="subscription-lifecycle" %}

- 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](https://developer.paddle.com/resources/overview.md), as well as [a Next.js starter kit](https://billing.new/) that includes core billing management.
- You can integrate [the customer portal](https://developer.paddle.com/concepts/customer-portal.md) to let customers cancel their subscription and update their payment details.
- You can use [webhook simulator](https://developer.paddle.com/webhooks/simulator.md) to simulate complex scenarios, like new signups and dunning workflows.

{% /collapsible %}

### 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](https://developer.paddle.com/concepts/sell/self-serve-checkout.md), or use [the invoicing functionality](https://developer.paddle.com/concepts/sell/sales-assisted-invoice.md) in Paddle Billing.

{% callout type="info" %}
If you're porting subscription data, you'll need to run Paddle Classic and Paddle Billing alongside each other for a short while. Start processing new subscriptions through Paddle Billing, while routing customers in Paddle Classic to your existing subscription workflows.
{% /callout %}

{% collapsible title="Good to know" id="transacting" %}

- If you [create and issue invoices](https://developer.paddle.com/build/invoices/create-issue-invoices.md) 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](https://developer.paddle.com/build/customers/create-update-customers.md) are shared between Paddle Classic and Paddle Billing.
- [Reporting](https://developer.paddle.com/build/finance/generate-reports.md) 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.

{% /collapsible %}

### 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](https://developer.paddle.com/migrate/paddle-classic/port-data.md) 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.

{% collapsible title="Good to know" id="port-subscriptions" %}

- 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`](https://developer.paddle.com/webhooks/subscriptions/subscription-imported.md) 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](https://developer.paddle.com/concepts/retain/payment-recovery-dunning.md) when their account is in good standing.

{% /collapsible %}

### Remove your Paddle Classic integration

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

{% collapsible title="Good to know" id="remove-classic" %}

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

{% /collapsible %}

### Integrate with Paddle Retain — live only

Paddle Billing integrates with [Paddle Retain](https://developer.paddle.com/concepts/retain/overview.md), 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](https://developer.paddle.com/concepts/retain/payment-recovery-dunning.md), [Cancellation Flows](https://developer.paddle.com/concepts/retain/cancellation-flows-surveys.md), and [Term Optimization](https://developer.paddle.com/concepts/retain/term-optimization.md) to proactively reduce churn and maximize customer lifetime value.

{% collapsible title="Good to know" id="retain" %}

- Paddle Retain powers dunning and payment recovery in Paddle Billing.
- Turn on and set up [Payment Recovery](https://developer.paddle.com/concepts/retain/payment-recovery-dunning.md) 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](https://developer.paddle.com/paddle-js/overview.md), so you don't need to include an additional script.

{% /collapsible %}