Skip to main content
LemonSqueezy is often the easiest hosted product flow for simple digital products because it is very product/variant oriented out of the box.

​
What You Are Setting Up

For LemonSqueezy, you need:
  1. products and variants
  2. checkout URLs for the app buttons
  3. a webhook endpoint
  4. a variant-to-purchase-type mapping

​
Required Env Vars

NEXT_PUBLIC_PAYMENT_PROVIDER=lemonsqueezy
NEXT_PUBLIC_CHECKOUT_URL_TEMPLATE=https://...
LEMON_SQUEEZY_WEBHOOK_SECRET=...
Optional UI checkout URLs: 
NEXT_PUBLIC_CHECKOUT_URL_PREMIUM=https://...
NEXT_PUBLIC_CHECKOUT_URL_ENTERPRISE=https://...
NEXT_PUBLIC_CHECKOUT_URL_AGENCY=https://...
NEXT_PUBLIC_CHECKOUT_URL_CREDITS_SMALL=https://...
NEXT_PUBLIC_CHECKOUT_URL_CREDITS_LARGE=https://...
Optional variant map: 
LEMON_SQUEEZY_VARIANT_MAP='{"123456":"anotherwrapper-enterprise"}'

​
Step 1: Create Your Products And Variants

In LemonSqueezy:
  1. Create the products you want to sell
  2. Create variants if needed
  3. Decide which variants represent:
    • Premium
    • Enterprise
    • Agency
    • Small credits
    • Large credits
In LemonSqueezy, the important internal identifier for this repo is usually the variant ID. Create the hosted checkout links you want your users to visit. Then paste those URLs into .env.local, for example: 
NEXT_PUBLIC_CHECKOUT_URL_ENTERPRISE=https://yourstore.lemonsqueezy.com/buy/...
NEXT_PUBLIC_CHECKOUT_URL_CREDITS_SMALL=https://yourstore.lemonsqueezy.com/buy/...

​
Step 3: Map LemonSqueezy Variants To Repo Purchase Types

The repo resolves LemonSqueezy purchases by variant ID. Example: 
LEMON_SQUEEZY_VARIANT_MAP='{"123456":"anotherwrapper-enterprise","123457":"credits-small"}'
That tells the app what each LemonSqueezy variant means inside your product.

​
Step 4: Add The Webhook

In LemonSqueezy:
  1. Open your webhook settings
  2. Add this endpoint:
https://yourdomain.com/api/payments/lemonsqueezy
  1. Copy the webhook secret into:
LEMON_SQUEEZY_WEBHOOK_SECRET=...

​
How The Repo Processes A Successful LemonSqueezy Payment

Once LemonSqueezy sends a paid order webhook:
  1. the repo verifies the webhook signature
  2. it reads the variant ID
  3. it maps that variant to a purchase type
  4. it stores the purchase in the database
  5. it updates credits or purchase state
If the variant is unknown, the purchase is ignored safely instead of applying the wrong result.

​
Verification Checklist

Your LemonSqueezy setup is working if:
  • the app opens the LemonSqueezy checkout page
  • LemonSqueezy shows a successful webhook delivery
  • a row appears in purchases
  • credits or plan state update correctly

​
Common LemonSqueezy Mistakes

  • creating the product but never saving the checkout URL in env
  • forgetting the webhook secret
  • using the wrong variant ID in LEMON_SQUEEZY_VARIANT_MAP
  • testing locally but leaving the webhook pointed at production

Payments Overview

Go back to the shared payment architecture and basics.