Lemon Squeezy winds down payment processing on March 31, 2027, so stores running on it need a new home for billing before then. This guide walks you through making Paddle Billing that home: what comes with you, how existing subscriptions move, how your catalog, checkout, and webhooks map across, and how to make the switch.
Lemon Squeezy estimates a migration can take up to eight weeks. For its own timeline and advice, see the migration hub.
Why Paddle
Like Lemon Squeezy, Paddle is a merchant of record. Paddle sells to customers on your behalf and takes on payments, sales tax, fraud, and compliance from the day your integration goes live.
Your integration on Paddle is built from the same pieces:
- Paddle Checkout as an overlay or inline checkout on a page you host, opened with Paddle.js.
- A product catalog of products and prices, with localized pricing, trials, and discounts.
- Subscriptions you can pause, cancel, upgrade, and downgrade, with proration handled for you.
- Webhooks for over 50 event types, with signature verification and a simulator.
- A hosted customer portal where customers manage subscriptions, payment methods, and invoices.
- Official SDKs for Node.js, PHP, Python, and Go, plus MCP servers, agent skills, and a CLI for building with AI tools.
- Pricing of 5% + 50¢ per transaction, with no monthly fee and no migration fee.
PayPal is available at checkout in supported currencies, alongside cards, Apple Pay, Google Pay, and local payment methods.
What happens to your Lemon Squeezy data
Most of your store has a home in Paddle: recreate your catalog, import subscriptions or re-create them through checkout, and keep your historical records in Lemon Squeezy. Use this table to see what applies to you.
| Lemon Squeezy data | What happens |
|---|---|
| Products, variants, and prices | You recreate them as Paddle products and prices. |
| Customers | Created in Paddle as subscriptions are imported or customers check out. There's nothing to import separately. |
| Card subscriptions that are active, trialing, paused, or past due | Paddle-assisted migration for eligible stores, or customer-led. Canceled subscriptions aren't imported. |
| Subscriptions not paid by card, such as PayPal or Cash App Pay | Customer-led migration. The payment details behind them can't be transferred. |
| One-time purchases | Nothing to migrate. Keep the order records, and any license keys or files, so existing customers keep what they bought. |
| Discounts | You recreate them as Paddle discounts. An assisted import can attach a discount to each subscription with its remaining billing periods; redemption history doesn't transfer. |
| Email audience | Not imported, and Paddle doesn't send marketing emails. Lemon Squeezy's subscriber export gives you the list for whichever email tool you use. |
| Orders, invoices, refunds, and payouts | Stay in Lemon Squeezy. Paddle is the record for activity after cutover. |
| License keys, files, and download links | Yours to rebuild. Paddle tells you when a purchase completes, and you generate keys and host files. |
| Affiliates | Not part of Paddle. Use a third-party affiliate tool such as Tolt, FirstPromoter, or Partnero. Lemon Squeezy Affiliates close on March 31, 2027, and referrals after that aren't tracked. |
Choose your migration path
There are two ways to move existing subscriptions. The right one depends on how customers pay, how many subscriptions you have, and how much action you're prepared to ask customers to take. Most migrations use both in parallel: Paddle imports card subscriptions while customers paying another way subscribe again.
| If this describes you | Start with |
|---|---|
| Most of your subscriptions are paid by card, and you don't want customers to enter payment details again | Paddle-assisted migration, if your store is eligible. A specialist confirms this when they review your request. |
| Anything else: you have a smaller store, you want to move gradually, or your subscriptions aren't paid by card | Customer-led migration. |
If your integration is a hosted checkout link, Paddle Checkout opens on a page you host, so allow time to build one and to replace your webhooks. If you use Lemon Squeezy for license keys or file delivery, plan their replacement separately.
Paddle-assisted migration
Paddle offers assisted migrations to eligible stores. Request a migration as soon as you've chosen this path: a migration specialist reviews your setup, confirms whether your store qualifies, walks you through the process, and shares the import template.
Lemon Squeezy also asks merchants moving to another provider to complete its migration intake form, under My account > Settings > Migration.
An assisted migration has three parts:
- The transfer of card details from Lemon Squeezy's payment processor into Paddle's vault.
- A file of subscriber data from you.
- The import, which matches the two: Paddle creates each subscription with the saved payment details behind it, so customers keep paying without entering card details again.
Your specialist arranges the transfer while you build. Card details move between the two vaults directly, so you don't handle or upload them, and how long it takes depends mostly on how quickly Lemon Squeezy provides the export.
Recreate your catalog in Paddle
Create products and prices in Paddle that match the Lemon Squeezy variants your subscribers are on, including prices for customers on legacy pricing, and any discounts you want to carry over. The import references them by Paddle ID. See Map your integration.
Paddle's sandbox and live accounts are separate, with separate IDs. Build in sandbox, but the import file needs the IDs from your live account.
Go live on Paddle
The import can't run until new customers are going through a Paddle checkout and nothing new is sold through Lemon Squeezy. Build your checkout and webhooks using Map your integration, test it, work through the go-live checklist, including account verification and domain approval, and switch new traffic. Once you're live, agree on an import date with your specialist.
Before that date, set up Paddle Retain and check the tax_mode on your prices, because imported subscriptions use them from their first renewal.
Prepare the subscriber file
Export active subscriptions from the Lemon Squeezy API and build a CSV from the template your specialist sends, one row per subscription. Expect to supply:
- The customer's email, country, and postal code. Postal codes are required in some countries because tax depends on them; the template lists which. The Lemon Squeezy API doesn't return them, so take them from the orders export.
- The subscription status, and its currency, which comes from the subscription's order.
- The next billing date, which must be in the future on import day. Take the freshest export you can, and ask your specialist which date to supply for paused and past due subscriptions.
- The Paddle price ID and quantity for each item on the subscription.
- A reference that links the row to the transferred payment details. Your specialist tells you which value to use.
- The Lemon Squeezy subscription ID, and optionally the customer ID, as external IDs.
You can also carry an existing Paddle discount onto each subscription, and add custom data such as the customer's ID in your own database so that subscription.imported carries it back to you.
Expect a test import on a sample before the real one. Use it to test your handling of subscription.imported: price ID matching, duplicate subscriptions, customers with more than one subscription, failed rows, and database updates.
Update your records on import day
Paddle imports the subscriptions and matches them to the transferred payment details. As each one lands, subscription.imported occurs, and you also get a file mapping Lemon Squeezy subscription IDs to Paddle IDs. Update your database with the new customer, subscription, and price IDs, and keep the old ones for support and reconciliation. Paddle bills each subscription on its next billing date. For any subscription whose payment details didn't transfer, ask the customer to subscribe again through a Paddle checkout, as in a customer-led migration. Schedule import day for when your engineering and support teams are available.
Stop billing in Lemon Squeezy
Once the Paddle subscriptions are active, cancel the matching subscriptions in Lemon Squeezy. A canceled Lemon Squeezy subscription keeps access until the end of its paid period, so customers aren't cut off. Subscriptions that renew close to the import date could be billed by both platforms, so agree with your specialist how to handle them.
Customer-led migration
In a customer-led migration, customers start a new subscription through a Paddle checkout, and you cancel the old one. It works for any payment method, and you control the timing. It's the route for subscriptions not paid by card, such as PayPal or Cash App Pay, whose payment details can't be transferred, and for stores that don't qualify for an assisted migration or would rather not run an import.
Go live on Paddle
Your Paddle checkout has to be live before customers can move to it. Create products and prices in Paddle that match the Lemon Squeezy variants your subscribers are on, including prices for customers on legacy pricing and any discounts you want to carry over. Build your checkout and webhooks using Map your integration, test it, work through the go-live checklist, including account verification and domain approval, and switch new traffic. From this point, nothing new is sold through Lemon Squeezy.
Before the first customer moves, set up Paddle Retain and check the tax_mode on your prices, because new subscriptions use them from their first renewal.
Build the migration checkout
Build one checkout in your app that every migrating customer goes through. Open it for the price that matches their Lemon Squeezy variant, prefilling the customer's email and passing the customer's ID in your own database as custom data, so the new subscription links back to the right account.
A new subscription bills immediately, so for customers who've already paid Lemon Squeezy for the current period, keep their existing billing date instead.
If the customer's Lemon Squeezy subscription is trialing, open the migration checkout for a price with a trial period, then change the trial end date to match. If it's paused, open the migration checkout for the zero price, replace the zero price with the real one with proration_billing_mode set to do_not_bill, then pause the new subscription immediately. When it resumes, Paddle starts a new billing period and bills the real price.
Ask customers to move
There are two ways:
- At natural moments. Open the migration checkout wherever a customer would otherwise meet Lemon Squeezy inside your app: the payment method update button, the plan change screen, or a failed payment recovery.
- With a direct ask. Email customers, explain the change, and link to the migration checkout, with or without an incentive. Expect some customers to miss it, and some dormant subscribers to cancel once reminded.
Start with the natural moments now, and send the direct ask early enough that customers who ignore it can be followed up before the deadline. To avoid churn, don't block access until customers subscribe again. Before the first checkout link goes out, tell customers what's changing.
Cancel each Lemon Squeezy subscription
When subscription.created occurs, match it to the account using the custom data, cancel the matching Lemon Squeezy subscription, and update your database with the Paddle IDs.
Keep existing billing dates
Move customers who have already paid Lemon Squeezy for the current period without charging them, and line up the new subscription with their existing renewal date:
- Create a recurring price with a unit price of zero.
- Open the migration checkout for the zero price. The customer saves their payment details and isn't charged.
- When
subscription.createdoccurs, replace the zero-priced item with the real price, withproration_billing_modeset todo_not_bill. - Change the billing date: set
next_billed_atto the Lemon Squeezy subscription'srenews_at, again withdo_not_bill. Paddle rejects anext_billed_atless than 30 minutes away.
The customer is first billed on their existing renewal date, at the real price.
Paddle emails the customer at each step: that their payment details were saved, that their subscription was updated, and that their billing date changed. Tell customers to expect these before they go through the checkout.
If the Lemon Squeezy renewal date has already passed, or is less than 30 minutes away, there's nothing to keep. Open the migration checkout for the real price, and the customer is billed at checkout.
Map your integration
This section maps each workflow in a Lemon Squeezy integration to the way it works in Paddle Billing. Use it to review your integration and work out what to build.
Set up your product catalog
Lemon Squeezy
A store has products, each with variants. Each variant is a single payment, a subscription, pay what you want, or a free lead magnet, and single payments and subscriptions use one pricing model: standard, package, volume, or graduated, with usage-based billing as an option.
Paddle Billing
Everything you offer is a product with related prices. Variants that differ only by price or billing period become prices on one product; variants that differ by feature set become separate products; legacy pricing becomes extra prices.
A lead magnet becomes a price with a unit price of zero. Pay what you want becomes a custom transaction per purchase, with the amount the customer chose as the price.
Open a checkout
Lemon Squeezy
Lemon Squeezy hosts your storefront and product pages. On your own site, lemon.js opens a checkout overlay from a link with the lemonsqueezy-button class or with LemonSqueezy.Url.Open(), and LemonSqueezy.Setup({ eventHandler }) receives Checkout.Success.
Paddle Billing
Paddle doesn't host product pages. Paddle Checkout opens as an overlay or inline on a page you host, using Paddle.js with a client-side token. Open it with HTML data attributes or Paddle.Checkout.open(), and listen for checkout.completed through eventCallback.
Link customers to your app
Lemon Squeezy
The ID of the customer in your own database goes in checkout[custom][user_id] on the checkout URL, or in checkout_data.custom through the API, and comes back in meta.custom_data on webhooks.
Paddle Billing
The ID of the customer in your own database goes in customData when opening a checkout, or custom_data on a transaction. It's copied to the subscription and comes back in webhook payloads. See work with custom data.
Handle orders and renewals
Lemon Squeezy
A one-time purchase creates an order. A renewal creates a subscription invoice.
Paddle Billing
Both are transactions. Renewals have an origin of subscription_recurring, and refunds are adjustments against a transaction.
Manage subscriptions
Lemon Squeezy
Statuses are on_trial, active, paused, past_due, unpaid, cancelled, and expired. A cancelled subscription keeps access until ends_at. Plan changes, pauses, and cancellations go through PATCH /v1/subscriptions/:id.
Paddle Billing
Statuses are trialing, active, past_due, paused, and canceled. A cancellation or pause set for the end of the period is a scheduled_change on an active subscription. After dunning, Paddle pauses or cancels the subscription based on your settings, so an unpaid subscription in Lemon Squeezy is paused or canceled in Paddle. See provision access and handle subscription state for what each status means for access, and change plans for making changes through the API.
Usage-based billing
Lemon Squeezy
Metered variants bill in arrears from usage records you report against a subscription item.
Paddle Billing
Usage-based billing (early access) is prepaid usage allowances with subscription plans, using meters and usage events. It doesn't bill usage in arrears. To bill usage in arrears, meter usage yourself and charge it each period as a one-time charge on a zero-priced subscription, as described in third-party metering and billing.
Offer discounts and trials
Lemon Squeezy
Discounts are percentage or fixed, and apply once, for a number of months, or forever. Free trials are set on a variant.
Paddle Billing
Discounts are percentage, flat, or flat per seat, recurring for a set number of billing periods or forever. Trials are a trial_period on a price, free or paid, with cardless trials available.
Let customers manage their subscription
Lemon Squeezy
Send customers to the store's hosted customer portal using the signed portal and payment update URLs on the subscription, valid for 24 hours. Customers can also log in to Lemon Squeezy to see their orders from every store.
Paddle Billing
Send customers to the hosted customer portal, which shows only your subscriptions. Create a portal session with the API for an authenticated link, with deep links for managing a subscription, cancellation, and updating payment details.
Receive webhooks
Lemon Squeezy
You set the signing secret. Verify X-Signature as an HMAC-SHA256 hex digest of the raw body. Payloads carry meta.event_name and meta.custom_data.
Paddle Billing
Paddle generates the secret for each notification destination. Verify Paddle-Signature with an official SDK, and deduplicate on event_id, because you may receive the same event more than once. See Map your webhooks for the event mapping.
Call the API
Lemon Squeezy
Send JSON:API bodies with a Bearer API key, and switch the same store into test mode. Build with the official JavaScript or Laravel SDK.
Paddle Billing
Send plain JSON bodies with a Bearer API key, and test against a separate sandbox account with its own IDs. Build with an official SDK for Node.js, PHP, Python, or Go. Rails apps on the Pay gem already have both platforms behind one interface.
Deliver license keys and files
Lemon Squeezy
Lemon Squeezy generates license keys, hosts files, and runs the License API your software calls to activate and validate keys.
Paddle Billing
Your app generates keys, hosts files, and validates keys. Generate the key or unlock the download in your webhook handler when transaction.completed occurs for a first purchase, and store it against the Paddle customer and subscription IDs. Revoke it when subscription.canceled occurs. See Paddle for digital products.
Export your existing keys and their activations from Lemon Squeezy and import them into your app. If your software validates against Lemon Squeezy's License API, ship a build that validates against your app early enough for customers to update before the shutdown.
Map your webhooks
Make an inventory of every Lemon Squeezy event your app handles, then subscribe to the Paddle equivalents.
| Lemon Squeezy event | Paddle event |
|---|---|
order_created | transaction.completed, or transaction.paid to act as soon as payment is captured, before Paddle finishes processing it |
order_refunded, subscription_payment_refunded | adjustment.created with an action of refund. Check its status: refunds that are approved automatically are created as approved. Refunds that need review are created as pending_approval, and adjustment.updated occurs when they're approved or rejected. |
customer_updated | customer.updated |
subscription_created | subscription.created, then subscription.activated or subscription.trialing |
subscription_updated | subscription.updated |
subscription_cancelled | subscription.updated with a scheduled_change.action of cancel. The subscription stays active until the end of the billing period, when subscription.canceled occurs. |
subscription_expired | subscription.canceled, or subscription.paused if payment recovery is set to pause |
subscription_resumed | subscription.updated with scheduled_change set to null |
subscription_paused, subscription_unpaused | subscription.paused, subscription.resumed |
subscription_payment_success | transaction.completed. For renewals, the transaction's origin is subscription_recurring. |
subscription_payment_failed | transaction.payment_failed, then subscription.past_due |
subscription_payment_recovered | transaction.completed for the past due transaction, then subscription.updated with a status of active |
license_key_created, license_key_updated | Generate keys when transaction.completed occurs for a first purchase. |
affiliate_activated | Handled by your affiliate tool. |
Make your handlers idempotent so retried events don't grant access or create records twice, then test them with the webhook simulator.
Make the switch
In addition to the steps for your chosen migration path, you need to export your Lemon Squeezy data, tell customers what's changing, and run both platforms until the last subscription has moved.
Export from Lemon Squeezy
Export everything you need to run your business and reconcile the migration before March 31, 2027. Your catalog is the only export you need before you build: Paddle products and prices are created from it. Subscriptions are needed when you prepare the subscriber file or move customers, and the rest is for your records:
- Products, variants, and prices from the API, including IDs, trial periods, setup fees, and tax settings.
- Active subscriptions from the API, including
customer_id,variant_id,status,renews_at,trial_ends_at,payment_processor, andcard_brand, which is empty for subscriptions not paid by card. - Customers from the API, with name, email, city, region, and country.
- Orders using Lemon Squeezy's order export, which is also the only source of postal codes.
- Refunds from the orders API, which marks refunded orders with
refundedandrefunded_amount. - Payouts and tax documents from your payout account.
- Discounts from the API, and which subscriptions use them.
- License keys and their activations from the API, if you deliver license keys.
Tell customers what's changing
A new name on a bank statement confuses customers who weren't warned. Explain that billing is moving to Paddle, when, whether anything about price, currency, or billing date changes, what the customer needs to do, how the charge appears on their statement, and where to manage their subscription and find invoices.
Customers don't get an email from Paddle when their subscription is imported. The first email they get from Paddle is for their next renewal, and depending on their country and billing period, a reminder before it. Customers who move through the migration checkout get Paddle's usual emails from the checkout onward.
Run both platforms for a while
Until the last Lemon Squeezy subscription is canceled, you'll have customers on both platforms. Store which provider each account bills through, keep both webhook handlers live, and send each customer to the right portal when they manage their subscription. Once everyone has moved, reconcile customers, subscriptions, prices, discounts, and access, and keep the ID mapping and your exports for support and audit.
Get help
- Request a migration to talk to a migration specialist about moving existing subscriptions.
- Install the
paddle-migrate-lemon-squeezyagent skill to have a coding agent do the Paddle side of the work: audit your codebase for Lemon Squeezy touchpoints, inventory your store, map variants to products and prices, rewrite checkout and webhooks with the other Paddle skills, and prepare the subscriber file. It doesn't transfer payment details or subscriptions. - Ask Paddle support if you get stuck while building.