Skip to main content

Lemon Squeezy

JetShip offers built-in support for Lemon Squeezy as an alternative payment provider. This guide will walk you through setting up Lemon Squeezy in your Next.js application.

⚙️ Configuration​

Step 1: Create a Lemon Squeezy Account​

If you don't already have a Lemon Squeezy account, you will need to create one. You can refer to the Lemon Squeezy Getting Started Guide for more details on setting up your account.

Step 2: Collect API Keys 🔑​

Once your account is set up, gather these credentials:

  1. API Keys:
    • Follow the guide on Creating API Keys
    • Add your API key to .env: 
      LEMON_SQUEEZY_API_KEY=your_api_key
  2. Store ID:
    • Find your store ID in the Settings > Stores section of your Lemon Squeezy dashboard
    • Add it to .env: 
      LEMON_SQUEEZY_STORE_ID=your_store_id

🛍️ Creating Products in Lemon Squeezy​

Step 1: Create Products​

  1. Log in to your Lemon Squeezy Dashboard
  2. Navigate to Store > Products
  3. Click + New Product

Step 2: Configure Product Variants​

For subscription plans with multiple billing options:

  1. Create variants for different billing intervals:

    • Example: "Pro Plan"
      • Variant 1: "Pro Monthly" ($29/month)
      • Variant 2: "Pro Yearly" ($290/year)

  2. For one-time products:

    • Only one variant is needed
    • Lemon Squeezy creates a default variant automatically

Step 3: Get Variant IDs​

After creating products:

  1. For multiple variants:

    • Go to the product
    • Find the Variants section
    • Click three dots next to each variant
    • Select Copy ID

  2. For single variant products:

    • Click three dots next to the product
    • Select Copy Variant ID

Configure in JetShip​

Update your billingConfig.ts with the Lemon Squeezy product and variant IDs. See the Billing Schema documentation for detailed configuration examples.

Setting Up Webhooks​

Lemon Squeezy webhooks help track purchases and subscriptions. We handle these key events:

  • order_created: When a new order is created
  • subscription_created: When a new subscription is created

Configure Webhooks​

  1. Go to your Lemon Squeezy Dashboard
  2. Navigate to Settings > Webhooks
  3. Click + Add New Webhook
  4. Enter your webhook URL: 
    https://your-domain.com/api/webhook
    • Replace your-domain.com with your actual domain
  5. Add Signing secret to the webhook, this ensures that the webhook requests are secure and properly authenticated.
  6. Copy the signing secret to your .env: 
    LEMON_SQUEEZY_WEBHOOK_SIGNATURE=your_webhook_signature
  7. Enable these events:
    • order_created
    • subscription_created
    • subscription_updated
  8. Save the webhook, All done!🎉
    • You’ve successfully set up your LemonSqueezy webhook to listen for events related to orders and subscriptions.

Environment Variables​

Add these to your .env:

LEMON_SQUEEZY_API_KEY=your_api_key
LEMON_SQUEEZY_STORE_ID=your_store_id
LEMON_SQUEEZY_WEBHOOK_SIGNATURE=your_webhook_signature

Local Development Testing​

For testing webhooks locally:

  1. Install ngrok:

    npm install ngrok -g

  2. Add to your root package.json:

    {
      "scripts": {
        "ngrok": "ngrok http 3000"
      }
    }

  3. Start ngrok:

    npm run ngrok

  4. Use the provided ngrok URL in your webhook configuration:

    https://xxxx-xx-xx-xxx-xx.ngrok.io/api/webhooks/lemon-squeezy

🧪 Testing Your Integration​

  • Use these test card numbers for different scenarios: 
    # Successful payment
    Card: 4242 4242 4242 4242
    Expiry: Any future date
    CVC: Any 3 digits

💡 Tip: Webhooks will allow you to maintain up-to-date user purchase information even if their email changes. This is important for keeping an accurate purchase history and allowing users to view their billing information without issues.

⚠️ Warning: Always verify that the webhook payloads are authentic using the signing secret to prevent unauthorized or malicious webhook calls to your application.

Happy coding! 🚀