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. To search these docs, send a GET request to https://paddle-docs-retrieval.kapa-paddle.workers.dev/?q=<question> with a URL-encoded question. No authentication needed.

Skip to content
Paddle Docs home

Migrate from Lemon Squeezy to Paddle

Choose a migration path, map your catalog, checkout, and webhooks, and make the switch before Lemon Squeezy stops processing transactions on March 31, 2027.

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:

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 dataWhat happens
Products, variants, and pricesYou recreate them as Paddle products and prices.
CustomersCreated 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 duePaddle-assisted migration for eligible stores, or customer-led. Canceled subscriptions aren't imported.
Subscriptions not paid by card, such as PayPal or Cash App PayCustomer-led migration. The payment details behind them can't be transferred.
One-time purchasesNothing to migrate. Keep the order records, and any license keys or files, so existing customers keep what they bought.
DiscountsYou 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 audienceNot 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 payoutsStay in Lemon Squeezy. Paddle is the record for activity after cutover.
License keys, files, and download linksYours to rebuild. Paddle tells you when a purchase completes, and you generate keys and host files.
AffiliatesNot 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 youStart with
Most of your subscriptions are paid by card, and you don't want customers to enter payment details againPaddle-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 cardCustomer-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:

  1. Create a recurring price with a unit price of zero.
  2. Open the migration checkout for the zero price. The customer saves their payment details and isn't charged.
  3. When subscription.created occurs, replace the zero-priced item with the real price, with proration_billing_mode set to do_not_bill.
  4. Change the billing date: set next_billed_at to the Lemon Squeezy subscription's renews_at, again with do_not_bill. Paddle rejects a next_billed_at less 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.

Lemon Squeezy
Paddle Billing

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 eventPaddle event
order_createdtransaction.completed, or transaction.paid to act as soon as payment is captured, before Paddle finishes processing it
order_refunded, subscription_payment_refundedadjustment.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_updatedcustomer.updated
subscription_createdsubscription.created, then subscription.activated or subscription.trialing
subscription_updatedsubscription.updated
subscription_cancelledsubscription.updated with a scheduled_change.action of cancel. The subscription stays active until the end of the billing period, when subscription.canceled occurs.
subscription_expiredsubscription.canceled, or subscription.paused if payment recovery is set to pause
subscription_resumedsubscription.updated with scheduled_change set to null
subscription_paused, subscription_unpausedsubscription.paused, subscription.resumed
subscription_payment_successtransaction.completed. For renewals, the transaction's origin is subscription_recurring.
subscription_payment_failedtransaction.payment_failed, then subscription.past_due
subscription_payment_recoveredtransaction.completed for the past due transaction, then subscription.updated with a status of active
license_key_created, license_key_updatedGenerate keys when transaction.completed occurs for a first purchase.
affiliate_activatedHandled 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, and card_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 refunded and refunded_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-squeezy agent 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.

Was this page helpful?