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

Reintegration checklist for Paddle Billing from Paddle Classic

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

AI summary

A complete reintegration checklist for moving from Paddle Classic to Paddle Billing, covering every step from activation and catalog setup through to porting subscription data and removing your Classic integration.

  • • Work through the checklist sequentially — each phase builds on the last, and the guide links to the relevant implementation guides at each step.
  • • You can start routing new transactions through Paddle Billing before porting existing subscriptions, letting you validate the integration with real traffic without disrupting Classic customers.
  • • Porting subscriptions is the final phase before removing your Classic integration — use the dashboard migration screens to move active subscriptions from Classic to Billing.

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.

What are you migrating?

Pick all that apply — content updates to match.

Checklist

Activate Paddle Billing and review settings

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.

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

  • 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 for a transaction. Your default payment link 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 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.

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

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

Build your product catalog

Your product catalog 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.

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

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

Integrate with your frontend

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.

Migrating in your frontend is a case of swapping out Paddle.js v1 for Paddle.js v2. Depending on your stack, you can use our npm package, our Next.js starter kit, and our SDKs to speed up integration.

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

    To learn more, see Include Paddle.js.

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

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

    To learn more, see Set your default payment link.

  • Paddle.js v2 works similarly to v1 but introduces new ways to include and initialize Paddle.js, a new Paddle.Initialize() method, updated parameters and methods, and a simplified event system.

    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 or build an inline checkout.

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

    To learn more, see Build a pricing page.

  • 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. Remove the Profitwell.js snippet.

    To learn more, see Initialize Paddle.js and Retain.

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.

  • 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 and Handle provisioning and fulfillment.

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

  • 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 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 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 and create a corresponding database record.

    If you bill by invoice, update your workflows to use transaction webhooks instead of invoicing webhooks.

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

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 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. You can use the customer portal to quickly add core workflows, rather than building them yourself.

  • 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, using Paddle Retain Cancellation Flows via Paddle.Retain.initCancellationFlow(), or building your own workflow with the cancel a subscription API operation.

    Provision your app so that customers don't have access once canceled.

  • 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 or build your own workflow using Paddle.js and the Paddle API.

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

  • 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 or Add or remove items.

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, or use the invoicing functionality in Paddle Billing.

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

  • 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 and Payment methods.

  • 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 and customers to Paddle Billing.

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

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

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.

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

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

Was this page helpful?