Lemon Squeezy Configuration Guide

Quick Start (15 minutes)

This guide will walk you through setting up Lemon Squeezy for PhotoSwipe Pro license sales and automated delivery.

Step 1: Create Lemon Squeezy Account

Go to https://lemonsqueezy.com
Click "Get Started" or "Sign Up"
Create account with your email
Verify your email address
Complete onboarding (business info, payment details)

Step 2: Create Your Product

Navigate to Products

In Lemon Squeezy dashboard, click "Products" in left sidebar
Click "+ New Product"

Configure Product Details

Basic Info:

Product Name: PhotoSwipe Pro - Site License

Description:

AI-powered alt text, captions, and ImageObject schema for your photo galleries.

Includes:
• Automatic SEO-optimized alt text generation
• AI-generated descriptive captions
• ImageObject schema for search engines
• Priority email support
• All updates while subscription active

Price: $99.00 USD
Billing: Annual subscription (recurring)

Product Image:

Upload a logo or screenshot of the Pro demo
Recommended size: 1200x630px

Enable License Keys (CRITICAL!)

Scroll to "License Keys" section
Toggle "Enable license keys" to ON
Configure license key settings:
- Format: Choose "Custom Format"
- Prefix: pswp_prod_
- Length: 32 characters (default)
- Activation Limit: Unlimited (or set to 1-5 for Site license)
- Example: pswp_prod_abc123def456...
Save Product

Get Product ID

After saving, click on the product

In the URL, note the product ID:

https://app.lemonsqueezy.com/products/PRODUCT_ID

Copy this ID - you'll need it for environment variables

Step 3: Create Additional License Tiers (Optional)

Repeat Step 2 for other tiers:

Agency License

Name: PhotoSwipe Pro - Agency License
Price: $299/year
License Keys: Enabled (same prefix)
Activation Limit: Unlimited

Enterprise License

Name: PhotoSwipe Pro - Enterprise License
Price: $999/year
License Keys: Enabled (same prefix)
Activation Limit: Unlimited

Step 4: Get API Credentials

Create API Key

Click Settings (gear icon) in left sidebar
Click "API" tab
Click "+ Create API Key"
Name: "PhotoSwipe Pro API"
Permissions: Select all (or at minimum: read/write for licenses, orders, subscriptions)
Click "Create"
COPY THE API KEY IMMEDIATELY - you won't see it again!
- Format: eyJ0eXAiOiJKV1QiLCJhbGc...

Get Store ID

Still in Settings → API
Look for "Store ID" at the top
Copy the numeric ID (e.g., 12345)

Step 5: Configure Webhook

Create Webhook

In Settings, click "Webhooks" tab
Click "+ Add endpoint"
Configure:
- Callback URL:
```
Production: https://photoflowseo.com/api/webhooks/lemonsqueezy
Development: Use ngrok (see below)
```
- Secret: Click "Generate" to create webhook secret
- COPY THE SECRET - you'll need it for environment variables

Select Events

Check these events:

✅ order_created (REQUIRED - triggers license delivery)
✅ subscription_created
✅ subscription_updated
✅ subscription_cancelled
✅ subscription_resumed
✅ subscription_expired
✅ license_key_created

Save Webhook

Click "Create webhook"

Step 6: Configure Environment Variables

Local Development (.env)

Create /Users/JJR/photo_swipe/.env:

# Lemon Squeezy API
LEMON_SQUEEZY_API_KEY=eyJ0eXAiOiJKV1QiLCJhbGc...  # From Step 4
LEMON_SQUEEZY_STORE_ID=12345  # From Step 4
LEMON_SQUEEZY_PRODUCT_ID=67890  # From Step 2 (Site License)
LEMON_SQUEEZY_WEBHOOK_SECRET=your_webhook_secret_here  # From Step 5

# Optional: Multiple products
LEMON_SQUEEZY_PRODUCT_ID_SITE=67890
LEMON_SQUEEZY_PRODUCT_ID_AGENCY=67891
LEMON_SQUEEZY_PRODUCT_ID_ENTERPRISE=67892

# Email Provider (Resend)
EMAIL_PROVIDER=resend
RESEND_API_KEY=re_your_key_here  # Get from resend.com

# Download Security
DOWNLOAD_SECRET=generate_random_secret_here  # Use: openssl rand -hex 32

# Site Configuration
SITE_URL=http://localhost:3001  # Development
# SITE_URL=https://photoflowseo.com  # Production

# OpenRouter (for AI captions)
OPENROUTER_API_KEY=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
AI_MODEL=openai/gpt-4o-mini

# Server
PORT=4001
NODE_ENV=development

Production (Vercel/Railway/Fly.io)

Add these as environment variables in your hosting dashboard:

LEMON_SQUEEZY_API_KEY=eyJ...
LEMON_SQUEEZY_STORE_ID=12345
LEMON_SQUEEZY_PRODUCT_ID=67890
LEMON_SQUEEZY_WEBHOOK_SECRET=whsec_...
EMAIL_PROVIDER=resend
RESEND_API_KEY=re_...
DOWNLOAD_SECRET=[random 64-char hex]
SITE_URL=https://photoflowseo.com
NODE_ENV=production

Step 7: Test Webhook Locally (Development)

Option A: Use ngrok (Recommended)

# Install ngrok
brew install ngrok  # macOS
# or download from ngrok.com

# Start your API server
PORT=4001 npm run api

# In another terminal, expose it
ngrok http 4001

# Copy the HTTPS URL (e.g., https://abc123.ngrok.io)

Update Lemon Squeezy webhook:

Temporarily change webhook URL to:

https://abc123.ngrok.io/api/webhooks/lemonsqueezy

Option B: Use webhook.site for testing

Go to https://webhook.site
Copy your unique URL
Set as Lemon Squeezy webhook URL
Create test order
See webhook payload in webhook.site
Copy payload and test locally:

curl -X POST http://localhost:4001/api/webhooks/lemonsqueezy \
  -H 'Content-Type: application/json' \
  -d '{"meta":{"event_name":"order_created"},"data":{...}}'

Step 8: Create Test Purchase

Enable Test Mode

In Lemon Squeezy dashboard, toggle "Test Mode" (top right)
You should see orange "Test Mode" banner

Create Test Product Order

Go to your product page in test mode
Click "Copy checkout link" or create a checkout
Open link in incognito/private browser window
Use test card:
- Card: 4242 4242 4242 4242
- Expiry: Any future date (e.g., 12/25)
- CVC: Any 3 digits (e.g., 123)
- ZIP: Any 5 digits (e.g., 12345)
Complete purchase

Verify Webhook Fired

Check Lemon Squeezy → Settings → Webhooks → View logs
Should see order_created event with 200 response

Check your API server logs:

📨 Webhook received: order_created
📧 [MOCK] License email would be sent to: test@example.com
License Key: pswp_prod_test123...

Check Email (if Resend configured)

Check the email address used in test purchase
Should receive "Your PhotoSwipe Pro License Key" email
Verify:
- License key is present
- Download link works
- Installation instructions are clear

Step 9: Integrate Checkout Page

Update checkout.mdx

Edit /Users/JJR/photo_swipe/demo-docs-website/src/pages/checkout.mdx:

---
title: Get PhotoSwipe Pro
---

# Choose Your License

import BrowserOnly from '@docusaurus/BrowserOnly';

## Site License - $99/year

Perfect for single website owners

<BrowserOnly>
{() => (
  <a 
    href="https://your-store.lemonsqueezy.com/checkout/buy/VARIANT_ID_SITE"
    className="button button--primary button--lg"
  >
    Buy Site License →
  </a>
)}
</BrowserOnly>

## Agency License - $299/year

For agencies managing multiple client sites

<BrowserOnly>
{() => (
  <a 
    href="https://your-store.lemonsqueezy.com/checkout/buy/VARIANT_ID_AGENCY"
    className="button button--primary button--lg"
  >
    Buy Agency License →
  </a>
)}
</BrowserOnly>

## Enterprise - $999/year

Unlimited domains, custom SLA, dedicated support

<BrowserOnly>
{() => (
  <a 
    href="https://your-store.lemonsqueezy.com/checkout/buy/VARIANT_ID_ENTERPRISE"
    className="button button--primary button--lg"
  >
    Buy Enterprise License →
  </a>
)}
</BrowserOnly>

Get Checkout Links

In Lemon Squeezy, go to your product
Click "Get checkout link"
Copy the link (contains variant ID)
Replace VARIANT_ID_SITE etc. in checkout.mdx

Step 10: Test End-to-End Flow

Full Test Checklist:

🔒 Security Checklist

Before Going Live:

DO NOT commit .env file to Git
Add .env to .gitignore
Use strong webhook secret (auto-generated by LS)
Use HTTPS for webhook endpoint in production
Verify webhook signature is being checked
Test with invalid webhook signatures
Set production SITE_URL correctly
Enable rate limiting on API endpoints
Set up error monitoring (Sentry, Datadog)

🐛 Troubleshooting

Webhook not firing

Check:

Webhook URL is correct and accessible
Server is running
Events are selected in LS webhook config
View webhook logs in LS dashboard

Fix:

# Test webhook manually
curl -X POST https://your-domain.com/api/webhooks/lemonsqueezy \
  -H 'Content-Type: application/json' \
  -H 'X-Signature: test' \
  -d '{"meta":{"event_name":"order_created"},"data":{}}'

Email not sending

Check:

EMAIL_PROVIDER=resend is set
RESEND_API_KEY is correct
Domain is verified in Resend
Check Resend dashboard for delivery status

Fix:

Look for email in spam folder
Check server logs for errors
Test Resend API directly

License key not in order

Check:

License keys are enabled in product settings
Product has license key format configured
Order was created (not just checkout viewed)

Fix:

Recreate product with license keys enabled
Test with new order

Download failing

Check:

Pro package exists: ls releases/
License validation working
API server running

Fix:

# Rebuild Pro package
npm run build-pro

# Test download endpoint
curl "http://localhost:4001/api/download/download/5.4.4?key=pswp_prod_test123"

📊 Monitor After Launch

Lemon Squeezy Dashboard

Check daily:

Orders (successful purchases)
Webhook delivery rate (should be 100%)
Failed payments
Subscription renewals

Your API Server

Monitor:

Webhook endpoint errors
Email delivery failures
Download metrics
License validation API usage

Resend Dashboard

Track:

Delivery rate (should be 99%+)
Open rate (60%+ for transactional)
Click-through rate (80%+ for download link)
Bounce rate (should be < 1%)

✅ You're Done!

Once you've completed all steps:

✅ Lemon Squeezy product configured
✅ API credentials stored securely
✅ Webhook configured and tested
✅ Environment variables set
✅ Test purchase successful
✅ Email delivered
✅ Download working
✅ Checkout page updated

You're ready to accept real payments! 🎉

Switch off Test Mode in Lemon Squeezy to go live.

📞 Need Help?

Lemon Squeezy Docs: https://docs.lemonsqueezy.com
Lemon Squeezy Support: support@lemonsqueezy.com
PhotoSwipe Pro: support@photoflowseo.com

Lemon Squeezy Configuration Guide

Quick Start (15 minutes)​

Step 1: Create Lemon Squeezy Account​

Step 2: Create Your Product​

Navigate to Products​

Configure Product Details​

Enable License Keys (CRITICAL!)​

Get Product ID​

Step 3: Create Additional License Tiers (Optional)​

Agency License​

Enterprise License​

Step 4: Get API Credentials​

Create API Key​

Get Store ID​

Step 5: Configure Webhook​

Create Webhook​

Select Events​

Save Webhook​

Step 6: Configure Environment Variables​

Local Development (.env)​

Production (Vercel/Railway/Fly.io)​

Step 7: Test Webhook Locally (Development)​

Option A: Use ngrok (Recommended)​

Option B: Use webhook.site for testing​

Step 8: Create Test Purchase​

Enable Test Mode​

Create Test Product Order​

Verify Webhook Fired​

Check Email (if Resend configured)​

Step 9: Integrate Checkout Page​

Update checkout.mdx​

Get Checkout Links​

Step 10: Test End-to-End Flow​

Full Test Checklist:​

🔒 Security Checklist​

Before Going Live:​

🐛 Troubleshooting​

Webhook not firing​

Email not sending​

License key not in order​

Download failing​

📊 Monitor After Launch​

Lemon Squeezy Dashboard​

Your API Server​

Resend Dashboard​

✅ You're Done!​

📞 Need Help?​

Quick Start (15 minutes)

Step 1: Create Lemon Squeezy Account

Step 2: Create Your Product

Navigate to Products

Configure Product Details

Enable License Keys (CRITICAL!)

Get Product ID

Step 3: Create Additional License Tiers (Optional)

Agency License

Enterprise License

Step 4: Get API Credentials

Create API Key

Get Store ID

Step 5: Configure Webhook

Create Webhook

Select Events

Save Webhook

Step 6: Configure Environment Variables

Local Development (.env)

Production (Vercel/Railway/Fly.io)

Step 7: Test Webhook Locally (Development)

Option A: Use ngrok (Recommended)

Option B: Use webhook.site for testing

Step 8: Create Test Purchase

Enable Test Mode

Create Test Product Order

Verify Webhook Fired

Check Email (if Resend configured)

Step 9: Integrate Checkout Page

Update checkout.mdx

Get Checkout Links

Step 10: Test End-to-End Flow

Full Test Checklist:

🔒 Security Checklist

Before Going Live:

🐛 Troubleshooting

Webhook not firing

Email not sending

License key not in order

Download failing

📊 Monitor After Launch

Lemon Squeezy Dashboard

Your API Server

Resend Dashboard

✅ You're Done!

📞 Need Help?