[ [0x31] Features ] Lemon Squeezy

Lemon Squeezy

> Accept global payments with automatic tax handling and merchant of record.

Overview

[ [0x31] STATUS ]

Lemon Squeezy is a merchant of record (MoR) that handles sales tax, VAT, and payment processing globally. Unlike Stripe where you're the merchant, Lemon Squeezy is the seller on your behalf - they handle all tax compliance, refunds, and chargebacks. Perfect for selling to customers worldwide without tax headaches.

Features

[ [0x01] MERCHANT_OF_ ]

STATUS: READY

DESC: Lemon Squeezy handles taxes, refunds, and compliance globally.

[ [0x02] GLOBAL_TAX_H ]

STATUS: READY

DESC: Automatic VAT, GST, and sales tax calculation and remittance.

[ [0x03] MULTIPLE_PAY ]

STATUS: READY

DESC: Cards, PayPal, and local payment methods supported.

[ [0x04] FRAUD_PROTEC ]

STATUS: READY

DESC: Built-in fraud detection and chargeback protection.

[ [0x05] WEBHOOK_EVEN ]

STATUS: READY

DESC: Real-time notifications for orders, subscriptions, and more.

[ [0x06] CUSTOMER_POR ]

STATUS: READY

DESC: Self-serve subscription management for your customers.

Setup

[ [0x01] CREATE LEMON SQUEEZY ACCOUNT ]

DESC: Go to lemonsqueezy.com and create a store. Complete your onboarding to enable payments.

[ [0x02] GET API KEYS ]

DESC: In Settings → API, create a new API key with full access. Copy your Store ID from the store settings.

[ [0x03] CREATE PRODUCTS ]

DESC: Go to Products and create items for each tier. Each product variant has a unique ID you'll use for checkout.

[ [0x04] ADD KEYS TO APP ]

DESC: Add these to your .env.local file

1$# Lemon Squeezy API Keys
2$LEMONSQUEEZY_API_KEY="your_api_key_here"
3$LEMONSQUEEZY_STORE_ID="your_store_id"
4$LEMONSQUEEZY_WEBHOOK_SECRET="your_webhook_secret"
5
6$# Product Variant IDs (from Lemon Squeezy dashboard)
7$NEXT_PUBLIC_LEMONSQUEEZY_VARIANT_STARTER="123456"
8$NEXT_PUBLIC_LEMONSQUEEZY_VARIANT_PRO="123457"
9$NEXT_PUBLIC_LEMONSQUEEZY_VARIANT_ENTERPRISE="123458"

[ [0x05] SETUP WEBHOOKS ]

DESC: In Settings → Webhooks, create a webhook pointing to your application's endpoint.

1$# Production webhook URL
2$https://your-domain.com/api/lemonsqueezy/webhook
3
4$# Events to subscribe to:
5$# - order_created
6$# - subscription_created
7$# - subscription_updated
8$# - subscription_cancelled
9$# - subscription_payment_success
10$# - subscription_payment_failed

Tip: Copy the webhook signing secret and add it as LEMONSQUEEZY_WEBHOOK_SECRET

Usage

[ [0xF7] CHECKOUT BUTTON COMPONENT ]

Create a checkout session and redirect to Lemon Squeezy

1"use client";
2
3import { useState } from "react";
4import { Button } from "@/components/ui/button";
5
6export function LemonSqueezyCheckout({ variantId, planName }) {
7  const [loading, setLoading] = useState(false);
8
9  const handleCheckout = async () => {
10    setLoading(true);
11    try {
12      const response = await fetch("/api/lemonsqueezy/checkout", {
13        method: "POST",
14        headers: { "Content-Type": "application/json" },
15        body: JSON.stringify({ variantId }),
16      });
17
18      const { url, error } = await response.json();
19
20      if (error) {
21        alert(error);
22        return;
23      }
24
25      // Redirect to Lemon Squeezy Checkout
26      window.location.href = url;
27    } catch (err) {
28      alert("Something went wrong. Please try again.");
29    } finally {
30      setLoading(false);
31    }
32  };
33
34  return (
35    <Button onClick={handleCheckout} disabled={loading}>
36      {loading ? "Loading..." : `Get ${planName}`}
37    </Button>
38  );
39}

[ [0x1F] API ROUTE: CREATE CHECKOUT ]

Server-side checkout creation

1// src/app/api/lemonsqueezy/checkout/route.ts
2import { NextResponse } from "next/server";
3import { auth } from "@/lib/auth";
4import { createLemonSqueezyCheckout } from "@/lib/lemonsqueezy";
5import { env } from "@/lib/env";
6
7export async function POST(req: Request) {
8  const session = await auth();
9  if (!session?.user) {
10    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
11  }
12
13  const { variantId } = await req.json();
14
15  try {
16    const checkoutUrl = await createLemonSqueezyCheckout({
17      variantId,
18      email: session.user.email!,
19      userId: session.user.id,
20      successUrl: `${env.client.NEXT_PUBLIC_APP_URL}/dashboard?success=true`,
21      cancelUrl: `${env.client.NEXT_PUBLIC_APP_URL}/pricing`,
22    });
23
24    return NextResponse.json({ url: checkoutUrl });
25  } catch (error) {
26    console.error("Lemon Squeezy checkout error:", error);
27    return NextResponse.json(
28      { error: "Failed to create checkout" },
29      { status: 500 }
30    );
31  }
32}

[ [0x61] WEBHOOK HANDLER ]

Handle Lemon Squeezy webhook events

1// src/app/api/lemonsqueezy/webhook/route.ts
2import { NextResponse } from "next/server";
3import crypto from "crypto";
4import { handleLemonSqueezyWebhook } from "@/lib/lemonsqueezy";
5import { env } from "@/lib/env";
6
7export async function POST(req: Request) {
8  const body = await req.text();
9  const signature = req.headers.get("X-Signature");
10
11  // Verify webhook signature
12  const hmac = crypto.createHmac("sha256", env.server.LEMONSQUEEZY_WEBHOOK_SECRET);
13  const digest = hmac.update(body).digest("hex");
14
15  if (signature !== digest) {
16    return NextResponse.json({ error: "Invalid signature" }, { status: 401 });
17  }
18
19  const event = JSON.parse(body);
20
21  try {
22    await handleLemonSqueezyWebhook(event);
23    return NextResponse.json({ received: true });
24  } catch (error) {
25    console.error("Webhook error:", error);
26    return NextResponse.json({ error: "Webhook failed" }, { status: 500 });
27  }
28}

Prerequisites

[ [0x80] BEFORE YOU START ]

├─ Completed Getting Started guide
├─ Database configured and running
├─ Environment variables set up (.env.local)
└─ Lemon Squeezy account with API key

Stripe vs Lemon Squeezy

[ [0xF7] COMPARISON ]

Stripe

• You are the merchant (handle taxes yourself)
• Lower fees: 2.9% + $0.30
• Full control over customer relationship
• More payment methods and features
• Better for B2B / US-focused

Lemon Squeezy

• They are the merchant (handle ALL taxes)
• Higher fees: 5% + $0.50
• Zero tax compliance burden
• Great for digital products/SaaS
• Better for global / B2C

[ [0x00] INFO ]

When to use Lemon Squeezy

Choose Lemon Squeezy if you sell to consumers globally and don't want to deal with VAT, GST, or sales tax registration in 100+ countries. The higher fees are worth it for the compliance peace of mind.

Webhook Events

[ [0xFE] WEBHOOK EVENTS ]

order_createdNew purchase completed

subscription_createdNew subscription started

subscription_updatedPlan changed or modified

subscription_cancelledSubscription ended

subscription_payment_failedPayment attempt failed

Common Questions

What fees does Lemon Squeezy charge?

5% + $0.50 per transaction. This includes all payment processing, tax handling, and fraud protection. No monthly fees.

How do payouts work?

Lemon Squeezy pays out weekly or monthly (your choice) via PayPal or bank transfer. There's a small delay while they handle tax remittance.

Can I use both Stripe and Lemon Squeezy?

Yes! Many SaaS apps use Stripe for B2B (where customers handle their own taxes) and Lemon Squeezy for B2C international sales.

Next Steps

[ [0x51] FREE TRIALS ]

Free Trials

Let users try your product before paying with trial periods.

[ [0xA0] STRIPE PAYMENTS ]

Stripe Setup

Set up Stripe for direct payment processing with lower fees.

Overview

[ [0x31] STATUS ]

Features

[ [0x01] MERCHANT_OF_ ]

STATUS: READY

DESC: Lemon Squeezy handles taxes, refunds, and compliance globally.

[ [0x02] GLOBAL_TAX_H ]

STATUS: READY

DESC: Automatic VAT, GST, and sales tax calculation and remittance.

[ [0x03] MULTIPLE_PAY ]

STATUS: READY

DESC: Cards, PayPal, and local payment methods supported.

[ [0x04] FRAUD_PROTEC ]

STATUS: READY

DESC: Built-in fraud detection and chargeback protection.

[ [0x05] WEBHOOK_EVEN ]

STATUS: READY

DESC: Real-time notifications for orders, subscriptions, and more.

[ [0x06] CUSTOMER_POR ]

STATUS: READY

DESC: Self-serve subscription management for your customers.

Setup

[ [0x01] CREATE LEMON SQUEEZY ACCOUNT ]

DESC: Go to lemonsqueezy.com and create a store. Complete your onboarding to enable payments.

[ [0x02] GET API KEYS ]

DESC: In Settings → API, create a new API key with full access. Copy your Store ID from the store settings.

[ [0x03] CREATE PRODUCTS ]

DESC: Go to Products and create items for each tier. Each product variant has a unique ID you'll use for checkout.

[ [0x04] ADD KEYS TO APP ]

DESC: Add these to your .env.local file

1$# Lemon Squeezy API Keys
2$LEMONSQUEEZY_API_KEY="your_api_key_here"
3$LEMONSQUEEZY_STORE_ID="your_store_id"
4$LEMONSQUEEZY_WEBHOOK_SECRET="your_webhook_secret"
5
6$# Product Variant IDs (from Lemon Squeezy dashboard)
7$NEXT_PUBLIC_LEMONSQUEEZY_VARIANT_STARTER="123456"
8$NEXT_PUBLIC_LEMONSQUEEZY_VARIANT_PRO="123457"
9$NEXT_PUBLIC_LEMONSQUEEZY_VARIANT_ENTERPRISE="123458"

[ [0x05] SETUP WEBHOOKS ]

DESC: In Settings → Webhooks, create a webhook pointing to your application's endpoint.

1$# Production webhook URL
2$https://your-domain.com/api/lemonsqueezy/webhook
3
4$# Events to subscribe to:
5$# - order_created
6$# - subscription_created
7$# - subscription_updated
8$# - subscription_cancelled
9$# - subscription_payment_success
10$# - subscription_payment_failed

Tip: Copy the webhook signing secret and add it as LEMONSQUEEZY_WEBHOOK_SECRET

Usage

[ [0xF7] CHECKOUT BUTTON COMPONENT ]

Create a checkout session and redirect to Lemon Squeezy

1"use client";
2
3import { useState } from "react";
4import { Button } from "@/components/ui/button";
5
6export function LemonSqueezyCheckout({ variantId, planName }) {
7  const [loading, setLoading] = useState(false);
8
9  const handleCheckout = async () => {
10    setLoading(true);
11    try {
12      const response = await fetch("/api/lemonsqueezy/checkout", {
13        method: "POST",
14        headers: { "Content-Type": "application/json" },
15        body: JSON.stringify({ variantId }),
16      });
17
18      const { url, error } = await response.json();
19
20      if (error) {
21        alert(error);
22        return;
23      }
24
25      // Redirect to Lemon Squeezy Checkout
26      window.location.href = url;
27    } catch (err) {
28      alert("Something went wrong. Please try again.");
29    } finally {
30      setLoading(false);
31    }
32  };
33
34  return (
35    <Button onClick={handleCheckout} disabled={loading}>
36      {loading ? "Loading..." : `Get ${planName}`}
37    </Button>
38  );
39}

[ [0x1F] API ROUTE: CREATE CHECKOUT ]

Server-side checkout creation

1// src/app/api/lemonsqueezy/checkout/route.ts
2import { NextResponse } from "next/server";
3import { auth } from "@/lib/auth";
4import { createLemonSqueezyCheckout } from "@/lib/lemonsqueezy";
5import { env } from "@/lib/env";
6
7export async function POST(req: Request) {
8  const session = await auth();
9  if (!session?.user) {
10    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
11  }
12
13  const { variantId } = await req.json();
14
15  try {
16    const checkoutUrl = await createLemonSqueezyCheckout({
17      variantId,
18      email: session.user.email!,
19      userId: session.user.id,
20      successUrl: `${env.client.NEXT_PUBLIC_APP_URL}/dashboard?success=true`,
21      cancelUrl: `${env.client.NEXT_PUBLIC_APP_URL}/pricing`,
22    });
23
24    return NextResponse.json({ url: checkoutUrl });
25  } catch (error) {
26    console.error("Lemon Squeezy checkout error:", error);
27    return NextResponse.json(
28      { error: "Failed to create checkout" },
29      { status: 500 }
30    );
31  }
32}

[ [0x61] WEBHOOK HANDLER ]

Handle Lemon Squeezy webhook events

1// src/app/api/lemonsqueezy/webhook/route.ts
2import { NextResponse } from "next/server";
3import crypto from "crypto";
4import { handleLemonSqueezyWebhook } from "@/lib/lemonsqueezy";
5import { env } from "@/lib/env";
6
7export async function POST(req: Request) {
8  const body = await req.text();
9  const signature = req.headers.get("X-Signature");
10
11  // Verify webhook signature
12  const hmac = crypto.createHmac("sha256", env.server.LEMONSQUEEZY_WEBHOOK_SECRET);
13  const digest = hmac.update(body).digest("hex");
14
15  if (signature !== digest) {
16    return NextResponse.json({ error: "Invalid signature" }, { status: 401 });
17  }
18
19  const event = JSON.parse(body);
20
21  try {
22    await handleLemonSqueezyWebhook(event);
23    return NextResponse.json({ received: true });
24  } catch (error) {
25    console.error("Webhook error:", error);
26    return NextResponse.json({ error: "Webhook failed" }, { status: 500 });
27  }
28}

Stripe vs Lemon Squeezy

[ [0xF7] COMPARISON ]

Stripe

• You are the merchant (handle taxes yourself)
• Lower fees: 2.9% + $0.30
• Full control over customer relationship
• More payment methods and features
• Better for B2B / US-focused

Lemon Squeezy

• They are the merchant (handle ALL taxes)
• Higher fees: 5% + $0.50
• Zero tax compliance burden
• Great for digital products/SaaS
• Better for global / B2C

[ [0x00] INFO ]

When to use Lemon Squeezy

Common Questions

What fees does Lemon Squeezy charge?

5% + $0.50 per transaction. This includes all payment processing, tax handling, and fraud protection. No monthly fees.

How do payouts work?

Lemon Squeezy pays out weekly or monthly (your choice) via PayPal or bank transfer. There's a small delay while they handle tax remittance.

Can I use both Stripe and Lemon Squeezy?

Yes! Many SaaS apps use Stripe for B2B (where customers handle their own taxes) and Lemon Squeezy for B2C international sales.