> For the complete documentation index, see [llms.txt](https://developer.paddle.com/llms.txt).
>
> 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. It returns a JSON array of `{content, source_url}`, most relevant first.

# 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](https://www.lemonsqueezy.com/blog/saying-goodbye-to-lemon-squeezy) 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](https://docs.lemonsqueezy.com/migration).

## Why Paddle

Like Lemon Squeezy, Paddle is a [merchant of record](https://developer.paddle.com/get-started/how-paddle-works.md). 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](https://developer.paddle.com/concepts/sell/self-serve-checkout.md) as an overlay or inline checkout on a page you host, opened with [Paddle.js](https://developer.paddle.com/paddle-js.md).
- A [product catalog](https://developer.paddle.com/build/products/create-products-prices.md) of products and prices, with [localized pricing](https://developer.paddle.com/build/products/offer-localized-pricing.md), [trials](https://developer.paddle.com/build/trials/create-trial.md), and [discounts](https://developer.paddle.com/build/products/offer-discounts-promotions-coupons.md).
- [Subscriptions](https://developer.paddle.com/build/subscriptions/replace-products-prices-upgrade-downgrade.md) you can pause, cancel, upgrade, and downgrade, with [proration](https://developer.paddle.com/concepts/subscriptions/proration.md) handled for you.
- [Webhooks](https://developer.paddle.com/webhooks.md) for over 50 event types, with signature verification and a [simulator](https://developer.paddle.com/webhooks/simulator/test-webhooks.md).
- A hosted [customer portal](https://developer.paddle.com/concepts/sell/customer-portal.md) where customers manage subscriptions, payment methods, and invoices.
- [Official SDKs](https://developer.paddle.com/sdks.md) for Node.js, PHP, Python, and Go, plus [MCP servers, agent skills, and a CLI](https://developer.paddle.com/sdks/ai.md) for building with AI tools.
- [Pricing](https://www.paddle.com/pricing) of 5% + 50¢ per transaction, with no monthly fee and no migration fee.

[PayPal](https://developer.paddle.com/concepts/payment-methods/paypal.md) 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](https://developer.paddle.com/build/products/create-products-prices.md). |
| 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](https://developer.paddle.com/build/products/offer-discounts-promotions-coupons.md). 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](https://tolt.com), [FirstPromoter](https://firstpromoter.com), or [Partnero](https://www.partnero.com). 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](#paddle-assisted-migration), if your store is eligible. A specialist confirms this when they review your [request](https://www.paddle.com/compare/lemon-squeezy). |
| Anything else: you have a smaller store, you want to move gradually, or your subscriptions aren't paid by card | [Customer-led migration](#customer-led-migration). |

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

### Paddle-assisted migration

Paddle offers assisted migrations to eligible stores. [Request a migration](https://www.paddle.com/compare/lemon-squeezy) 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.

{% steps %}
{% step-item title="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](https://developer.paddle.com/build/products/offer-discounts-promotions-coupons.md) you want to carry over. The import references them by Paddle ID. See [Map your integration](#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.
{% /step-item %}
{% step-item title="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](#map-your-integration), test it, work through the [go-live checklist](https://developer.paddle.com/build/go-live-checklist.md), 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](https://developer.paddle.com/concepts/retain.md) and check the `tax_mode` on your prices, because imported subscriptions use them from their first renewal.
{% /step-item %}
{% step-item title="Prepare the subscriber file" %}
Export active subscriptions from the [Lemon Squeezy API](https://docs.lemonsqueezy.com/api/subscriptions/list-all-subscriptions) 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](https://docs.lemonsqueezy.com/help/orders/exporting-orders).
- 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`](https://developer.paddle.com/webhooks/subscriptions/subscription-imported.md) 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`](https://developer.paddle.com/webhooks/subscriptions/subscription-imported.md): price ID matching, duplicate subscriptions, customers with more than one subscription, failed rows, and database updates.
{% /step-item %}
{% step-item title="Update your records on import day" %}
Paddle imports the subscriptions and matches them to the transferred payment details. As each one lands, [`subscription.imported`](https://developer.paddle.com/webhooks/subscriptions/subscription-imported.md) 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](#customer-led-migration). Schedule import day for when your engineering and support teams are available.
{% /step-item %}
{% step-item title="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.
{% /step-item %}
{% /steps %}

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

{% steps %}
{% step-item title="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](https://developer.paddle.com/build/products/offer-discounts-promotions-coupons.md) you want to carry over. Build your checkout and webhooks using [Map your integration](#map-your-integration), test it, work through the [go-live checklist](https://developer.paddle.com/build/go-live-checklist.md), 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](https://developer.paddle.com/concepts/retain.md) and check the `tax_mode` on your prices, because new subscriptions use them from their first renewal.
{% /step-item %}
{% step-item title="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](https://developer.paddle.com/build/checkout/prefill-checkout-properties.md) and passing the customer's ID in your own database as [custom data](https://developer.paddle.com/build/transactions/custom-data.md), 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](#keep-existing-billing-dates) instead.

If the customer's Lemon Squeezy subscription is trialing, open the migration checkout for a price with a [trial period](https://developer.paddle.com/build/trials/create-trial.md), then [change the trial end date](https://developer.paddle.com/build/trials/extend-activate-change-date-trials.md) to match. If it's paused, open the migration checkout for the zero price, [replace the zero price with the real one](https://developer.paddle.com/build/subscriptions/replace-products-prices-upgrade-downgrade.md) with `proration_billing_mode` set to `do_not_bill`, then [pause](https://developer.paddle.com/build/subscriptions/pause-subscriptions.md) the new subscription immediately. When it resumes, Paddle starts a new billing period and bills the real price.
{% /step-item %}
{% step-item title="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](#tell-customers-whats-changing).
{% /step-item %}
{% step-item title="Cancel each Lemon Squeezy subscription" %}
When [`subscription.created`](https://developer.paddle.com/webhooks/subscriptions/subscription-created.md) occurs, match it to the account using the custom data, cancel the matching Lemon Squeezy subscription, and update your database with the Paddle IDs.
{% /step-item %}
{% /steps %}

#### 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](https://developer.paddle.com/build/subscriptions/replace-products-prices-upgrade-downgrade.md), with `proration_billing_mode` set to `do_not_bill`.
4. [Change the billing date](https://developer.paddle.com/build/subscriptions/change-billing-dates.md): set `next_billed_at` to the Lemon Squeezy subscription's `renews_at`, again with `do_not_bill`. Paddle [rejects](https://developer.paddle.com/errors/subscriptions/subscription_next_billed_at_too_soon.md) 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.

### 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](https://developer.paddle.com/build/products/create-products-prices.md). 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](https://developer.paddle.com/build/transactions/bill-create-custom-items-prices-products.md) 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](https://developer.paddle.com/build/checkout/build-overlay-checkout.md) or [inline](https://developer.paddle.com/build/checkout/build-branded-inline-checkout.md) on a page you host, using [Paddle.js](https://developer.paddle.com/paddle-js.md) with a client-side token. Open it with HTML data attributes or [`Paddle.Checkout.open()`](https://developer.paddle.com/paddle-js/methods/paddle-checkout-open.md), and listen for [`checkout.completed`](https://developer.paddle.com/paddle-js/events/checkout-completed.md) 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](https://developer.paddle.com/build/transactions/custom-data.md).

### Handle orders and renewals

#### Lemon Squeezy

A one-time purchase creates an order. A renewal creates a subscription invoice.

#### Paddle Billing

Both are [transactions](https://developer.paddle.com/build/transactions/create-transaction.md). Renewals have an `origin` of `subscription_recurring`, and refunds are [adjustments](https://developer.paddle.com/build/transactions/create-transaction-adjustments.md) 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](https://developer.paddle.com/build/subscriptions/provision-access-webhooks.md) for what each status means for access, and [change plans](https://developer.paddle.com/build/subscriptions/replace-products-prices-upgrade-downgrade.md) 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)](https://developer.paddle.com/build/usage-based-billing.md) 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](https://developer.paddle.com/get-started/how-paddle-works/ai-companies.md#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](https://developer.paddle.com/build/products/offer-discounts-promotions-coupons.md) are percentage, flat, or flat per seat, recurring for a set number of billing periods or forever. [Trials](https://developer.paddle.com/build/trials/create-trial.md) are a `trial_period` on a price, free or paid, with [cardless trials](https://developer.paddle.com/build/trials/cardless-trials.md) 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](https://developer.paddle.com/build/customers/integrate-customer-portal.md), which shows only your subscriptions. [Create a portal session](https://developer.paddle.com/api-reference/customer-portals/create-customer-portal-session.md) with the API for an authenticated link, with deep links for managing a subscription, cancellation, and [updating payment details](https://developer.paddle.com/build/subscriptions/update-payment-details.md).

### 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](https://developer.paddle.com/webhooks/about/notification-destinations.md). Verify `Paddle-Signature` with an [official SDK](https://developer.paddle.com/webhooks/about/signature-verification.md), and deduplicate on `event_id`, because you may receive the same event [more than once](https://developer.paddle.com/webhooks/about/how-webhooks-work.md). See [Map your webhooks](#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](https://developer.paddle.com/api-reference/about/authentication.md), and test against a [separate sandbox account](https://developer.paddle.com/sdks/sandbox.md) with its own IDs. Build with an [official SDK](https://developer.paddle.com/sdks/libraries.md) for Node.js, PHP, Python, or Go. Rails apps on the [Pay gem](https://developer.paddle.com/sdks/community/pay-gem.md) 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`](https://developer.paddle.com/webhooks/transactions/transaction-completed.md) occurs for a first purchase, and store it against the Paddle customer and subscription IDs. Revoke it when [`subscription.canceled`](https://developer.paddle.com/webhooks/subscriptions/subscription-canceled.md) occurs. See [Paddle for digital products](https://developer.paddle.com/get-started/how-paddle-works/digital-products.md).

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`](https://developer.paddle.com/webhooks/transactions/transaction-completed.md), or [`transaction.paid`](https://developer.paddle.com/webhooks/transactions/transaction-paid.md) to act as soon as payment is captured, before Paddle finishes processing it |
| `order_refunded`, `subscription_payment_refunded` | [`adjustment.created`](https://developer.paddle.com/webhooks/adjustments/adjustment-created.md) 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`](https://developer.paddle.com/webhooks/adjustments/adjustment-updated.md) occurs when they're approved or rejected. |
| `customer_updated` | [`customer.updated`](https://developer.paddle.com/webhooks/customers/customer-updated.md) |
| `subscription_created` | [`subscription.created`](https://developer.paddle.com/webhooks/subscriptions/subscription-created.md), then [`subscription.activated`](https://developer.paddle.com/webhooks/subscriptions/subscription-activated.md) or [`subscription.trialing`](https://developer.paddle.com/webhooks/subscriptions/subscription-trialing.md) |
| `subscription_updated` | [`subscription.updated`](https://developer.paddle.com/webhooks/subscriptions/subscription-updated.md) |
| `subscription_cancelled` | [`subscription.updated`](https://developer.paddle.com/webhooks/subscriptions/subscription-updated.md) with a `scheduled_change.action` of `cancel`. The subscription stays active until the end of the billing period, when [`subscription.canceled`](https://developer.paddle.com/webhooks/subscriptions/subscription-canceled.md) occurs. |
| `subscription_expired` | [`subscription.canceled`](https://developer.paddle.com/webhooks/subscriptions/subscription-canceled.md), or [`subscription.paused`](https://developer.paddle.com/webhooks/subscriptions/subscription-paused.md) if payment recovery is set to pause |
| `subscription_resumed` | [`subscription.updated`](https://developer.paddle.com/webhooks/subscriptions/subscription-updated.md) with `scheduled_change` set to `null` |
| `subscription_paused`, `subscription_unpaused` | [`subscription.paused`](https://developer.paddle.com/webhooks/subscriptions/subscription-paused.md), [`subscription.resumed`](https://developer.paddle.com/webhooks/subscriptions/subscription-resumed.md) |
| `subscription_payment_success` | [`transaction.completed`](https://developer.paddle.com/webhooks/transactions/transaction-completed.md). For renewals, the transaction's `origin` is `subscription_recurring`. |
| `subscription_payment_failed` | [`transaction.payment_failed`](https://developer.paddle.com/webhooks/transactions/transaction-payment-failed.md), then [`subscription.past_due`](https://developer.paddle.com/webhooks/subscriptions/subscription-past-due.md) |
| `subscription_payment_recovered` | [`transaction.completed`](https://developer.paddle.com/webhooks/transactions/transaction-completed.md) for the past due transaction, then [`subscription.updated`](https://developer.paddle.com/webhooks/subscriptions/subscription-updated.md) with a `status` of `active` |
| `license_key_created`, `license_key_updated` | Generate keys when [`transaction.completed`](https://developer.paddle.com/webhooks/transactions/transaction-completed.md) 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](https://developer.paddle.com/webhooks/simulator/test-webhooks.md).

## 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](https://docs.lemonsqueezy.com/api/products/list-all-products), including IDs, trial periods, setup fees, and tax settings.
- **Active subscriptions** from the [API](https://docs.lemonsqueezy.com/api/subscriptions/list-all-subscriptions), 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](https://docs.lemonsqueezy.com/api/customers/list-all-customers), with name, email, city, region, and country.
- **Orders** using Lemon Squeezy's [order export](https://docs.lemonsqueezy.com/help/orders/exporting-orders), which is also the only source of postal codes.
- **Refunds** from the orders [API](https://docs.lemonsqueezy.com/api/orders/list-all-orders), which marks refunded orders with `refunded` and `refunded_amount`.
- **Payouts and tax documents** from your payout account.
- **Discounts** from the [API](https://docs.lemonsqueezy.com/api/discounts/list-all-discounts), and which subscriptions use them.
- **License keys** and their activations from the [API](https://docs.lemonsqueezy.com/api/license-keys/list-all-license-keys), 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](https://www.paddle.com/compare/lemon-squeezy) to talk to a migration specialist about moving existing subscriptions.
- Install the `paddle-migrate-lemon-squeezy` [agent skill](https://developer.paddle.com/sdks/ai/agent-skills.md) 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](https://www.paddle.com/help) if you get stuck while building.