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

# Reintegration checklist for Paddle Billing from Paddle Classic

Everything you need to do when reintegrating with Paddle Billing from Paddle Classic.

---

Ready to start your reintegration with Paddle Billing? This guide outlines all the steps that you need to set up Paddle Billing, update your integration, and prepare for go-live.

After you've reintegrated with Paddle Billing, you can [port your subscriptions from Paddle Classic to Paddle Billing](https://developer.paddle.com/migrate/paddle-classic/port-data.md).

## Checklist

### Activate Paddle Billing and review settings

Most settings are shared between Paddle Classic and Paddle Billing. This includes [payment methods](https://developer.paddle.com/concepts/payment-methods/overview.md), [checkout branding options](https://developer.paddle.com/build/checkout/brand-customize-inline-checkout.md), 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 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.

    You can switch between Paddle Classic and Paddle Billing in the Paddle dashboard using the toggle at the bottom-right.

- [ ] **Set default payment link**

    Paddle Billing automatically generates a payment link for transactions you create, using your default payment link as a base. It's a quick way to open [Paddle Checkout](https://developer.paddle.com/concepts/sell/self-serve-checkout.md) for a transaction. Your default payment link should be a page that [includes Paddle.js](https://developer.paddle.com/paddle-js/include-paddle-js.md), typically your checkout page.

    Go to **Paddle > Checkout > Checkout settings**, then add a default payment link. Set this to a domain that you've verified for use on Paddle. You can always change this later.

    To learn more, see [Set your default payment link](https://developer.paddle.com/build/transactions/default-payment-link.md).

- [ ] **Review your currency settings**

    Paddle Billing can automatically convert prices into the best currency for a location at checkout. Choose the currencies you want 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 want Paddle to automatically convert. We recommend turning on all currencies.

    To learn more, see [Localize prices](https://developer.paddle.com/build/products/offer-localized-pricing.md).

- [ ] **Generate new API keys**

    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, then store them securely.

    Send a request to the `/event-types` endpoint to test your authentication.

    To learn more, see [Authentication](https://developer.paddle.com/api-reference/about/authentication.md).

### Build your product catalog

Your [product catalog](https://developer.paddle.com/build/products/create-products-prices.md) includes subscription plans, recurring addons, and one-off items.

Paddle Billing offers a more flexible way of structuring your catalog, and includes support for multi-product subscriptions. This is a great chance to review how your prices are modeled.

- [ ] **Create products and prices**

    Products describe the items that customers can purchase. They have related prices that describe how they're charged. Add products and prices to Paddle for your subscription plans, recurring addons, and one-off items.

    As part of the migration process, you can map plans in Paddle Classic to products in Paddle Billing.

    Go to **Paddle > Catalog > Products** to start adding products and prices.

    To learn more, see [Create products and prices](https://developer.paddle.com/build/products/create-products-prices.md).

- [ ] **Create discounts**

    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.

    In Paddle Billing, discounts replace functionality offered by coupons, modifiers, and charges. You might like to come back to this step after you've ported your subscriptions to Paddle Billing.

    Go to **Paddle > Catalog > Discounts** to start adding discounts.

    To learn more, see [Create discounts](https://developer.paddle.com/build/products/offer-discounts-promotions-coupons.md).

### Integrate with your frontend

Paddle Billing comes with a new version of [Paddle Checkout](https://developer.paddle.com/concepts/sell/self-serve-checkout.md), 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](https://developer.paddle.com/concepts/sell/sales-assisted-invoice.md) by card or other payment method.

Migrating in your frontend is a case of swapping out Paddle.js v1 for [Paddle.js v2](https://developer.paddle.com/paddle-js/overview.md). Depending on your stack, you can use our [npm package](https://github.com/PaddleHQ/paddle-js-wrapper), our [Next.js starter kit](https://billing.new/), and [our SDKs](https://developer.paddle.com/paddle-js/include-paddle-js.md) to speed up integration.

{% callout type="info" %}
You might encounter problems including Paddle.js v1 and v2 on the same page. We recommend creating new pages for your Paddle Billing checkout and frontend workflows. Contact us at [sellers@paddle.com](mailto:sellers@paddle.com) if you need to include Paddle.js v1 and Paddle.js v2 on the same page.
{% /callout %}

- [ ] **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()`](https://developer.paddle.com/paddle-js/methods/paddle-initialize.md) in your frontend.

    To learn more, see [Include Paddle.js](https://developer.paddle.com/paddle-js/include-paddle-js.md).

- [ ] **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 want your default payment link page to be different from your checkout page, build a new page that [includes Paddle.js](https://developer.paddle.com/paddle-js/include-paddle-js.md).

    Go to **Paddle > Checkout > Checkout settings** then update your default payment link.

    To learn more, see [Set your default payment link](https://developer.paddle.com/build/transactions/default-payment-link.md).

- [ ] **Upgrade your checkout and signup workflow**

    Paddle.js v2 works similarly to v1 but introduces new ways to include and initialize Paddle.js, a new [`Paddle.Initialize()`](https://developer.paddle.com/paddle-js/methods/paddle-initialize.md) method, updated parameters and methods, and [a simplified event system](https://developer.paddle.com/paddle-js/events/overview.md).

    Include and initialize Paddle.js v2, swap authentication to use a client-side token, pass an array of items to your open checkout function, and update event callbacks.

    To learn more, see [Build an overlay checkout](https://developer.paddle.com/build/checkout/build-overlay-checkout.md) or [build an inline checkout](https://developer.paddle.com/build/checkout/build-branded-inline-checkout.md).

- [ ] **Upgrade your pricing page**

    Paddle Billing introduces a new [`Paddle.PricePreview()`](https://developer.paddle.com/paddle-js/methods/paddle-pricepreview.md) 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()`](https://developer.paddle.com/paddle-js/methods/paddle-pricepreview.md) in your pricing page.

    To learn more, see [Build a pricing page](https://developer.paddle.com/build/checkout/build-pricing-page.md).

- [ ] **Integrate with Paddle Retain — live accounts only**

    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()`](https://developer.paddle.com/paddle-js/methods/paddle-initialize.md) calls to include `pwCustomer`, passing either the Paddle ID or email address of a customer. Remove the `Profitwell.js` snippet.

    To learn more, see [Initialize Paddle.js and Retain](https://developer.paddle.com/paddle-js/include-paddle-js#import-initialize-paddlejs-retain.md).

### 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/list-events.md), and comprehensive documentation that you can use to build your own fulfillment workflows.

- [ ] **Create notification destinations**

    Create notification destinations to tell Paddle where to deliver webhook notifications and which events you want to receive notifications for. There's no primary endpoint in Paddle Billing.

    Build or update your webhook handler function, then go to **Paddle Developer tools > Notifications** to start creating notification destinations.

    To learn more, see [Create notification destinations](https://developer.paddle.com/webhooks/notification-destinations.md) and [Handle provisioning and fulfillment](https://developer.paddle.com/build/subscriptions/provision-access-webhooks.md).

- [ ] **Update signature verification**

    For security, verify webhook signatures to make sure received webhooks are genuinely sent from Paddle. This helps you be sure they haven't been tampered with in-transit.

    Signature verification in Paddle Billing works by using a `Paddle-Signature` header and a secret key, rather than a signature in the payload. It doesn't require PHP serialization.

    Update your webhook signature verification workflow for Paddle Billing. Our SDKs include helper functions and classes to do this for you.

    To learn more, see [Verify webhook signatures](https://developer.paddle.com/webhooks/signature-verification.md).

- [ ] **Update your order fulfillment workflow**

    When a customer completes a purchase, you need to handle fulfillment.

    In Paddle Classic, Paddle handles sending license keys and digital downloads. In Paddle Billing, you'll need to build this yourself. You can listen for [`transaction.completed`](https://developer.paddle.com/webhooks/transactions/transaction-completed.md) webhooks to build your own fulfillment workflows.

    Paddle Billing automatically creates a new subscription for recurring items where a checkout completes or an invoice is issued.

    For one-time items, create your own workflow to generate license keys and send digital downloads, and consider using the [customer portal](https://developer.paddle.com/concepts/customer-portal.md) for customer invoice management.

    Subscriptions are created automatically in Paddle Billing when a checkout completes or an invoice is issued; ensure you also [provision your app](https://developer.paddle.com/build/subscriptions/provision-access-webhooks.md) and create a corresponding database record.

    If you [bill by invoice](https://developer.paddle.com/concepts/sell/sales-assisted-invoice.md), update your workflows to use transaction webhooks instead of invoicing webhooks.

- [ ] **Create new tables in your database**

    To avoid data contamination, we recommend creating new tables in your database for subscription data rather than enriching existing records.

    Customers can have more than one subscription in Paddle Billing, so we recommend creating a table for customer data and a separate table for subscription data, then relating them using the customer ID.

    Create new tables in your database for customer and subscription data.

    To learn more, see [Prepare your database](https://developer.paddle.com/migrate/paddle-classic/port-data#pre-migration-database.md).

### Build subscription lifecycle workflows

In your backend, update workflows that handle subscription lifecycle events, like when customers upgrade or downgrade, or pause or cancel their subscription. You can use [our SDKs](https://developer.paddle.com/resources/overview.md) to speed up the process.

The [Paddle Billing API](https://developer.paddle.com/api-reference/overview.md) gives you more access to your data, and includes a new [subscription entity](https://developer.paddle.com/api-reference/subscriptions/overview.md) that you can map to a subscription record in your database. You can use the customer portal to quickly add core workflows, rather than building them yourself.

{% callout type="info" %}
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.
{% /callout %}

- [ ] **Update your cancel a subscription workflow**

    You should provide a way for customers to cancel their subscription when they no longer want to use your app.

    For compliance, emails from Paddle include a link to cancel subscriptions.

    Let customers cancel their subscription by integrating with the [customer portal](https://developer.paddle.com/build/customers/integrate-customer-portal.md), using [Paddle Retain Cancellation Flows](https://developer.paddle.com/build/retain/configure-cancellation-flows-surveys.md) via [`Paddle.Retain.initCancellationFlow()`](https://developer.paddle.com/paddle-js/methods/paddle-retain-initcancellationflow.md), or building your own workflow with the [cancel a subscription](https://developer.paddle.com/build/subscriptions/cancel-subscriptions.md) API operation.

    [Provision your app](https://developer.paddle.com/build/subscriptions/provision-access-webhooks.md) so that customers don't have access once canceled.

- [ ] **Update your payment method update workflow**

    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. Either [integrate with the customer portal](https://developer.paddle.com/build/customers/integrate-customer-portal.md) or build [your own workflow using Paddle.js and the Paddle API](https://developer.paddle.com/build/subscriptions/update-payment-details.md).

- [ ] **Update your pause and resume subscription workflow**

    Pausing a subscription is more intuitive in Paddle Billing, and lets you specify a date that subscriptions should resume.

    Build a workflow to let customers pause and resume their subscription. Provision your app so that customers have limited access while paused.

    To learn more, see [Pause a subscription](https://developer.paddle.com/build/subscriptions/pause-subscriptions.md).

- [ ] **Update your upgrade and downgrade workflows**

    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.

    To learn more, see [Upgrade or downgrade](https://developer.paddle.com/build/subscriptions/replace-products-prices-upgrade-downgrade.md) or [Add or remove items](https://developer.paddle.com/build/subscriptions/add-remove-products-prices-addons.md).

### Start transacting through Paddle Billing

At this point, you're ready to start transacting through 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 in Paddle Billing](https://developer.paddle.com/concepts/sell/sales-assisted-invoice.md).

If you offer subscriptions, start processing new subscriptions through Paddle Billing, while routing customers in Paddle Classic to your existing subscription logic.

- [ ] **Test your integration and go live**

    Test payment, fulfillment, and subscription lifecycle scenarios to check that your integration works. When you're happy, go live.

    Run through your checkout or invoicing workflow to make sure that everything works. If you offer subscriptions, you can use webhook simulator to test subscription lifecycle events like new signups, dunning, and cancellations.

    To learn more, see [Webhook simulator](https://developer.paddle.com/webhooks/simulator.md) and [Payment methods](https://developer.paddle.com/concepts/payment-methods/overview.md).

- [ ] **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.

### Port subscription data to Billing

Now you're running through Paddle Billing, use the screens in the dashboard to [port your Paddle Classic subscriptions](https://developer.paddle.com/migrate/paddle-classic/port-data.md) and customers to Paddle Billing.

- [ ] **Handle imported entities**

    When customers and subscriptions are migrated, `imported` events occur in Paddle Billing. We recommend building logic to create customer and subscription records in your database when they've been imported.

    Subscribe to webhooks for [`subscription.imported`](https://developer.paddle.com/webhooks/subscriptions/subscription-imported.md) 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.

    To learn more, see [Port your subscriptions](https://developer.paddle.com/migrate/paddle-classic/port-data.md).

- [ ] **Port your subscriptions**

    Use the screens in the Paddle dashboard to migrate your subscriptions to Paddle Billing. The aim of migration is to move all your subscriptions to Paddle Billing, so you can turn off your Paddle Classic integration.

    Historic reporting data remains on Paddle Classic.

    Go to **Paddle > Migrate** to start. Make sure you toggle **Paddle Billing** in the nav bar first.

    To learn more, see [Port your subscriptions](https://developer.paddle.com/migrate/paddle-classic/port-data.md).

### Remove your Paddle Classic integration

Once you've completed the preceding steps, 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 dashboard 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.

    To learn more, see [Developer changelog](https://developer.paddle.com/changelog/overview.md).