Lemon Squeezy
How to integrate Lemon Squeezy for payments and subscriptions.
Optional Feature
Stripe is the default payment gateway integrated in StarterKitPro. This guide explains how to replace Stripe with Lemon Squeezy.
Setup
Follow these steps to integrate Lemon Squeezy into your StarterKit Pro application.
Removing Stripe (If Switching)
If you are switching from the default Stripe integration, follow these steps first:
- Uninstall Stripe Package:
Terminal - Remove Stripe Environment Variables: Delete these lines from your
.env.local
:.env.local - Remove Stripe Configuration: Delete Stripe-related config from
lib/app-config.ts
. - Remove Stripe Schema Fields: Remove
priceId
field from yourprisma/schema.prisma
. - Remove Stripe Lib: Delete the file
lib/stripe.ts
. - Remove Stripe Webhook: Delete the folder
app/api/webhook/stripe
.
Install the Lemon Squeezy package
Install the official Lemon Squeezy JavaScript library:
Add the environment variables
Add the following variables to your .env.local
file:
LEMONSQUEEZY_API_KEY
: Create a new API key from your Lemon Squeezy dashboard under Settings > API.LEMONSQUEEZY_STORE_ID
: Find your store ID under Settings > Stores. Copy only the numeric ID (without the#
).LEMONSQUEEZY_SIGNING_SECRET
: Generate a random, secure string. This is used to verify webhook signatures.
Get Product/Variant ID
- Create a new product in your Lemon Squeezy dashboard under Store > Products.
- Ensure you add at least one variant to the product, even if it has a single price.
- Navigate to the variant's details page. The
variantId
is the number in the URL after/variants/
. (e.g.,https://app.lemonsqueezy.com/product/[productId]/variants/[variantId]
)
Code Implementation
Now, update the necessary files in your codebase.
Update your config
Modify your application configuration:
Update your User file model
Adjust your Prisma schema to include Lemon Squeezy customer/subscription fields:
Run Commands
Run npm run db:generate
and npm run db:push
to apply the changes to your
database.
Update your Pricing component
Adjust the pricing component to fetch Lemon Squeezy plans/variants:
Update your PurchaseButton component
Modify the purchase button to initiate Lemon Squeezy checkout:
Update your CustomerPortalButton component
Update the customer portal button to redirect users to their Lemon Squeezy billing portal:
Update your payment-actions file
Add server actions related to Lemon Squeezy checkout and portal:
Create a lemonsqueezy lib
Create a utility file for interacting with the Lemon Squeezy API:
Update appConfig References
Update references to Stripe with Lemon Squeezy in these files:
Webhook Setup
Add Webhook URL
- Go to Settings > Webhooks in your Lemon Squeezy dashboard.
- Click "Create webhook".
- Enter your application's webhook endpoint URL (e.g.,
https://yourdomain.com/api/webhook/lemonsqueezy
). - Paste the
LEMONSQUEEZY_SIGNING_SECRET
you generated earlier into the "Signing secret" field. - Select the events you want to subscribe to (e.g.,
subscription_created
,subscription_updated
,order_created
). - Save the webhook.
Create Webhook API Route
Create the API route handler to process incoming webhooks:
Test vs. Live Mode
Lemon Squeezy provides a Test Mode for development and testing purposes, allowing you to simulate transactions without processing real payments. Understanding the differences between Test and Live modes is crucial.
Enabling Test Mode
- You can toggle Test Mode on or off directly within your Lemon Squeezy dashboard. Look for a switch, usually located in the header or sidebar.
Key Considerations for Test Mode
- Store ID: Your
LEMONSQUEEZY_STORE_ID
remains the same for both Test and Live modes. - API Key: You must generate separate API keys for Test Mode and Live Mode. Ensure you use the correct key (
LEMONSQUEEZY_API_KEY
) corresponding to the mode you are operating in (Test during development, Live for production). - Test Products/Variants: You must create separate products and variants while in Test Mode. Use the
variantId
s from these test products in your application during development. Live products/variants are not accessible in Test Mode, and vice versa. - Test Webhooks: Webhook events triggered in Test Mode are separate from Live Mode events. If you need to test webhooks, configure your webhook endpoint (e.g.,
/api/webhook/lemonsqueezy
) to receive test events under Settings > Webhooks while Test Mode is active. You might need a separate Signing Secret for test webhooks or use the same one. - Test Card: Use Lemon Squeezy's provided test card numbers to simulate purchases.