Lemon Squeezy

You are integrating Lemon Squeezy as a payment gateway into a [Django / Next.js / etc.] application. Lemon Squeezy is a Merchant of Record — it handles all tax collection, compliance, and payment processing on your behalf.

## Setup
1. Create a Lemon Squeezy account and wait for approval (can take days)
2. Create your products and variants in the Lemon Squeezy Dashboard
3. Generate an API key from Settings > API in the Dashboard
4. Store credentials in environment variables — NEVER hardcode them:
   - `LEMONSQUEEZY_API_KEY` (your API key)
   - `LEMONSQUEEZY_STORE_ID` (your store ID)
   - `LEMONSQUEEZY_WEBHOOK_SECRET` (webhook signing secret)

## Option A: Checkout Overlay (Recommended for most use cases)
The simplest integration — embed Lemon.js and open a checkout overlay:

```html
<script src="https://app.lemonsqueezy.com/js/lemon.js" defer></script>
<a href="https://yourstore.lemonsqueezy.com/buy/variant-id" class="lemonsqueezy-button">Buy Now</a>
```

Lemon.js (2.3kB) intercepts the link and opens a checkout overlay on your page.

## Option B: API-Driven Checkout
Create a checkout session programmatically:

```javascript
import { lemonSqueezySetup, createCheckout } from '@lemonsqueezy/lemonsqueezy.js';

lemonSqueezySetup({ apiKey: process.env.LEMONSQUEEZY_API_KEY });

const checkout = await createCheckout(process.env.LEMONSQUEEZY_STORE_ID, variantId, {
  checkoutData: {
    email: customer.email,
    custom: { user_id: customer.id },
  },
  productOptions: {
    redirectUrl: 'https://yourdomain.com/success',
  },
});

// Redirect user to checkout.data.attributes.url
```

## Webhook Handling (Critical)
Never rely on the success redirect alone — always confirm via webhooks:

1. Set up a webhook endpoint in Settings > Webhooks or via the API
2. Listen for key events:
   - `order_created` — one-time purchase completed
   - `subscription_created` — new subscription started
   - `subscription_updated` — plan changed, paused, or resumed
   - `subscription_cancelled` — subscription ended
   - `subscription_payment_success` — recurring payment processed
   - `subscription_payment_failed` — payment retry needed
   - `license_key_created` — new license key issued
3. ALWAYS verify the webhook signature:
```javascript
import crypto from 'crypto';

function verifyWebhook(rawBody, signatureHeader, secret) {
  const hmac = crypto.createHmac('sha256', secret);
  const digest = hmac.update(rawBody).digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(digest),
    Buffer.from(signatureHeader)
  );
}

// In your webhook handler:
const signature = req.headers['x-signature'];
if (!verifyWebhook(req.rawBody, signature, process.env.LEMONSQUEEZY_WEBHOOK_SECRET)) {
  return res.status(401).send('Invalid signature');
}

const event = JSON.parse(req.body);
const eventName = event.meta.event_name;
const customData = event.meta.custom_data; // { user_id: '...' }
```
4. Return 200 quickly, then process asynchronously
5. Track processed event IDs to prevent duplicate fulfillment

## License Key Validation (for software products)
```javascript
import { validateLicense } from '@lemonsqueezy/lemonsqueezy.js';

const result = await validateLicense({ licenseKey: 'XXXXX-XXXXX-XXXXX-XXXXX' });
if (result.data.valid) {
  // License is active
}
```

## Important Notes
- The API follows JSON:API spec — set headers: `Accept: application/vnd.api+json` and `Content-Type: application/vnd.api+json`
- All amounts are in cents (e.g., $10 = 1000)
- Use Test Mode for development — create test API keys and simulate subscription events
- Lemon Squeezy handles ALL tax calculation and collection — do NOT add your own tax logic
- All settlements are in USD — your customers see local currency prices but you receive USD
- The `custom_data` field in checkout is how you link Lemon Squeezy orders to your internal user IDs

## Testing
- Toggle Test Mode in the Dashboard to create test products and orders
- Use the 'Simulate event' option on test subscriptions to trigger webhook events
- Test card: use Stripe test cards (4242 4242 4242 4242) in test mode
- Verify webhook signature verification works correctly before going live

## Common Gotchas
- Account approval is required before you can accept real payments — apply early
- Webhook events use `meta.event_name` not a top-level `type` field (unlike Stripe)
- Custom data passed at checkout comes back in `meta.custom_data` in webhooks
- The 50¢ flat fee means products under $10 have disproportionately high effective rates
- All payouts are in USD — plan for FX conversion if you're outside the US
- 13-day hold on funds plus bi-monthly payout schedule means delayed cash flow