> ## Documentation Index
> Fetch the complete documentation index at: https://docs.anotherwrapper.com/llms.txt
> Use this file to discover all available pages before exploring further.

# LemonSqueezy

> Step-by-step guide to setting up LemonSqueezy checkout and webhooks

LemonSqueezy is often the easiest path to accepting payments -- it's super product/variant oriented out of the box, which means less configuration for you. Let's get it running.

## What you're setting up

Four things to make LemonSqueezy work:

1. Products and variants in LemonSqueezy
2. Checkout URLs for your app buttons
3. A webhook endpoint
4. A variant-to-purchase-type mapping

## Env vars

<CodeGroup>
  ```env Required theme={null}
  NEXT_PUBLIC_PAYMENT_PROVIDER=lemonsqueezy
  NEXT_PUBLIC_CHECKOUT_URL_TEMPLATE=https://...
  LEMON_SQUEEZY_WEBHOOK_SECRET=...
  ```

  ```env Optional checkout URLs theme={null}
  NEXT_PUBLIC_CHECKOUT_URL_PLAN_SMALL=https://...
  NEXT_PUBLIC_CHECKOUT_URL_PLAN_MEDIUM=https://...
  NEXT_PUBLIC_CHECKOUT_URL_PLAN_LARGE=https://...
  NEXT_PUBLIC_CHECKOUT_URL_CREDITS_SMALL=https://...
  NEXT_PUBLIC_CHECKOUT_URL_CREDITS_LARGE=https://...
  ```

  ```env Optional variant map theme={null}
  LEMON_SQUEEZY_VARIANT_MAP='{"123456":"plan-medium"}'
  ```
</CodeGroup>

## Setup

<Steps>
  <Step title="Create your products and variants">
    Head to your [LemonSqueezy dashboard](https://app.lemonsqueezy.com/) and create the products you want to sell.

    Create variants if needed, and decide which ones represent:

    * Small / Medium / Large plans
    * Small / Large credit packs

    <Info>
      In LemonSqueezy, the **variant ID** is the important identifier this repo uses to map purchases. Keep track of those IDs.
    </Info>
  </Step>

  <Step title="Create your checkout links">
    Create hosted checkout links for each product you want to sell, then paste them into `.env.local`:

    ```env theme={null}
    NEXT_PUBLIC_CHECKOUT_URL_PLAN_MEDIUM=https://yourstore.lemonsqueezy.com/buy/...
    NEXT_PUBLIC_CHECKOUT_URL_CREDITS_SMALL=https://yourstore.lemonsqueezy.com/buy/...
    ```
  </Step>

  <Step title="Map variants to purchase types">
    The repo resolves LemonSqueezy purchases by variant ID. Tell it what each variant means:

    ```env theme={null}
    LEMON_SQUEEZY_VARIANT_MAP='{"123456":"plan-medium","123457":"credits-small"}'
    ```

    This is how your app knows that variant `123456` is a medium plan purchase and variant `123457` is a small credits pack.
  </Step>

  <Step title="Add the webhook">
    In your LemonSqueezy webhook settings, add this endpoint:

    ```text theme={null}
    https://yourdomain.com/api/payments/lemonsqueezy
    ```

    Then copy the webhook secret into your env:

    ```env theme={null}
    LEMON_SQUEEZY_WEBHOOK_SECRET=...
    ```

    <Warning>
      Without the webhook configured, payments succeed in LemonSqueezy but your app will never know about them. Credits won't be added and purchases won't be stored.
    </Warning>
  </Step>
</Steps>

## How it works under the hood

Once LemonSqueezy sends a paid order webhook:

1. The repo verifies the webhook signature
2. It reads the variant ID from the event
3. It maps that variant to a purchase type via `LEMON_SQUEEZY_VARIANT_MAP`
4. It stores the purchase in the database
5. It updates credits or purchase state

<Info>
  If the variant ID is unknown (not in your map), the purchase is safely ignored rather than applying the wrong result. No data gets corrupted.
</Info>

## Verify your setup

<Check>
  **Your LemonSqueezy setup is working if all of these are true:**

  * The app opens the LemonSqueezy checkout page
  * LemonSqueezy shows a successful webhook delivery
  * A row appears in your `purchases` table
  * Credits or plan state update correctly
</Check>

<AccordionGroup>
  <Accordion title="Created the product but nothing shows in the app">
    You probably created the product in LemonSqueezy but forgot to save the checkout URL in your `.env.local` file. The app needs those URLs to build payment buttons.
  </Accordion>

  <Accordion title="Webhook verification fails">
    Double-check that `LEMON_SQUEEZY_WEBHOOK_SECRET` matches what's in your LemonSqueezy webhook settings. A typo or stale value will cause silent failures.
  </Accordion>

  <Accordion title="Payment succeeds but purchase type is wrong">
    Check that the variant ID in `LEMON_SQUEEZY_VARIANT_MAP` matches the actual variant ID from LemonSqueezy. You can find this in the product settings.
  </Accordion>

  <Accordion title="Works locally but not in production (or vice versa)">
    Make sure your webhook URL points to the right environment. If you're testing locally, it should point to your local tunnel. In production, it should point to your production domain.
  </Accordion>
</AccordionGroup>

<Card title="Payments Overview" icon="money-bill" href="/payments">
  Go back to the shared payment architecture and basics.
</Card>