LemonSqueezy Payment Setup Guide

Overview

This guide provides a detailed walkthrough for setting up LemonSqueezy payments in your application. It covers everything from account creation to webhook configuration, ensuring a smooth integration process for both test and live environments.

Set Up LemonSqueezy Account

Sign up for LemonSqueezy
- Begin by signing up on LemonSqueezy (opens in a new tab) and creating a new account. Once signed in, you will be asked to create a new store.
- Enter your store name, store URL, and country.
- It’s best to use your domain name as the store URL. Use the country where your business is legally registered.
- Click "Create my store" to proceed.
Activate Your Store
- After creating your store, click on "Activate Store" to proceed.
Add Business Details
- Fill in the following business details:
  - Your full name
  - Name of your registered business
  - Business address
  - Website URL
- If you don’t have a legal business yet, many users operate using a Single Member LLC in the USA. You can use Firstbase.io (opens in a new tab) to register your business in the US. (Recommendation only; please do your own research.)
- You will be asked additional questions about your business. Answer them to the best of your ability.
- Finally, click "Submit".
Verify Your Identity
- To verify your identity, head to the Settings > General page in your Lemon Squeezy dashboard and click on the “Verify your identity” button.
- You will be asked to connect to Stripe for the verification process. LemonSqueezy is owned by Stripe and operates using Stripe under the hood.
- If you are already verified with Stripe, you will be approved without much delay.
- You will be asked to provide some personal information and upload a photo of your government-issued ID.
- Once your identity has been verified and your store has been activated, you will be able to start selling products on Lemon Squeezy.
- You will be also asked to provide your bank details for payouts.
- Scroll down to the "Store Settings" section and fill in the required information. Upload your logo and other details.
Configure Payout Method
- Go to Settings > Payouts in your LemonSqueezy dashboard.
- Connect your Bank Account or PayPal, and select one of them as the default payout method.

Create Product

Test mode

Test mode allows you to simulate transactions during the development phase. You can test all features before going live.

Toggle test mode on
Add Product
- Go to Store > **Products"" and click on "New Product" button.
- Now you have to add a new product to your store. Fill in a name and description for your product.
- You can select Pricing as "Single Payment" or "Subscription". Subscription is for recurring payments.
- Set the pricing model as "Standard Pricing".
- Set a price for your product if you selected "Single Payment".
- Set a price and a billing cycle (e.g., month, year) for your product if you selected "Subscription".
- Fill up the rest of the details.
- Then click on "Add Variant" button under the Variants section.
- Fill the same details for the variant as you did for the product. Then click on "Save and go back" button.
- Fill any other details necessary and click on "Publish Product" button.
Copy the variant-id from the product page
- Inside the product, click on the variant to view the variant-id.
- It is of the format https://app.lemonsqueezy.com/products/[product-id]/variants/[variant-id]
- Copy the variant-id. We will use this in the following steps.

Live Mode

This is the mode you want to use in production. Follow the same steps as Test Mode, but with test mode toggled off.

Webhook and LemonSqueezy Environment Variables Setup

Test mode

Set environment variables
- Open the .env.local file in your project's root folder. If it doesn't exist, rename .env.example to .env.local.
- In LemonSqueezy, ensure Test Mode is on.
- Get API Key
  - Navigate to Settings > API and click on the + icon on top right.
  - Enter a name for your API key, set an expiration date, and click Create API Key
  - Copy the generated API key immediately as it won't be shown again
- Get Store ID
  - Then navigate to Settings > Stores in your LemonSqueezy dashboard.
  - Copy the Store ID (exclude the # symbol)
- Create Signing Secret
  - Generate a signing secret between 6-40 characters.
  - This secret validates incoming webhooks from LemonSqueezy.
  - Either create your own random string or use the generator below.
  - Click on the Generate button to generate a random string. The key is cryptographically generated using the Web Crypto API, ensuring secure and unpredictable randomness for production use.
- Set the keys in .env.local as follows:
  - LEMONSQUEEZY_API_KEY: API Key from LemonSqueezy
  - LEMONSQUEEZY_STORE_ID: Store ID from LemonSqueezy
  - LEMONSQUEEZY_SIGNING_SECRET: Signing Secret that you generated or typed in the previous step.

Note: If you're working in a live test server, you might configure this key differently, such as within the server's environment variable settings.

Set up webhooks
- Go to Settings > Webhooks in LemonSqueezy to configure webhooks for events like order creation and subscription expiration.
- You can listen to LemonSqueezy events in two ways while in test mode:
  
  a. Using ngrok:
  - Tools like ngrok allow you to create a secure tunnel to your local server, making it accessible over the internet.
  - Download and install ngrok following this tutorial: ngrok Documentation (opens in a new tab).
  - Run ngrok http http://localhost:3000 in your terminal (On Mac) or PowerShell (On Windows). This will generate a https URL. Make sure you use the correct port number where your localhost NextJS app is running!
  - Now you will copy the https URL generated by ngrok and use it as the webhook endpoint URL in LemonSqueezy.
  - In Settings > Webhooks, click on the + icon on top right to create a new webhook.
  - Set Callback URL as: [ngrok_https_url]/api/payments/lemonsqueezy/webhook
  - Enter your signing secret that you generated or typed in the previous step into the Signing Secret field. This is used to validate incoming webhooks from LemonSqueezy for security purposes.
  - Select the order and subscription events shown in the screenshot below so that you can listen to these events.
  - Then click on "Save Webhook"
  - Make sure that you dont close the ngrok terminal or PowerShell as it will stop generating the https URL and your webhook will stop working.
  - If you do close it, you can reopen it by running the same command ngrok http http://localhost:3000 in your terminal (On Mac) or PowerShell (On Windows). And copy the new https URL and repeat the process above.
  b. Using a live endpoint:
  - In Settings > Webhooks, click on the + icon on top right to create a new webhook.
  - Set Callback URL as: https://www.yourdomain.com/api/payments/lemonsqueezy/webhook. Just replace www.yourdomain.com with your actual domain.
  - Enter your signing secret that you generated or typed in the previous step into the Signing Secret field. This is used to validate incoming webhooks from LemonSqueezy for security purposes.
  - Select the order and subscription events shown in the screenshot below so that you can listen to these events.
  - Then click on "Save Webhook"
  - Now, LemonSqueezy events for payments will be listened to by the above endpoint. Make sure your website is deployed at https://www.yourdomain.com.

Live Mode

Repeat the process above with your live keys and endpoints like given below.

Set environment variables
- Open the .env.local file in your project's root folder. If it doesn't exist, rename .env.example to .env.local.
- In LemonSqueezy, ensure Test Mode is off.
- Get API Key
  - Navigate to Settings > API and click on the + icon on top right.
  - Enter a name for your API key, set an expiration date, and click Create API Key
  - Copy the generated API key immediately as it won't be shown again
- Get Store ID
  - Then navigate to Settings > Stores in your LemonSqueezy dashboard.
  - Copy the Store ID (exclude the # symbol)
- Create Signing Secret
  - Generate a signing secret between 6-40 characters.
  - This secret validates incoming webhooks from LemonSqueezy.
  - Either create your own random string or use the generator below.
  - Click on the Generate button to generate a random string. The key is cryptographically generated using the Web Crypto API, ensuring secure and unpredictable randomness for production use.
- Set the keys in .env.local as follows:
  - LEMONSQUEEZY_API_KEY: API Key from LemonSqueezy
  - LEMONSQUEEZY_STORE_ID: Store ID from LemonSqueezy
  - LEMONSQUEEZY_SIGNING_SECRET: Signing Secret that you generated or typed in the previous step.

Note: As you're working in a live server, you might configure this key differently, such as within the server's environment variable settings.

Set up webhooks
- In LemonSqueezy, ensure Test Mode is off.
- In Settings > Webhooks, click on the + icon on top right to create a new webhook.
- Set Callback URL as: https://www.yourdomain.com/api/payments/lemonsqueezy/webhook. Just replace www.yourdomain.com with your actual domain.
- Enter your signing secret that you generated or typed in the previous step into the Signing Secret field. This is used to validate incoming webhooks from LemonSqueezy for security purposes.
- Select the order and subscription events shown in the screenshot below so that you can listen to these events.
- Then click on "Save Webhook"
- Now, LemonSqueezy events for payments will be listened to by the above endpoint. Make sure your website is deployed at https://www.yourdomain.com.

Supabase Environment Variables Setup

We use Supabase to store customer information. Ensure the following keys are configured:

NEXT_PUBLIC_SUPABASE_URL: Your Supabase project URL
SUPABASE_SERVICE_ROLE_KEY: Your Supabase service role key

For more details, refer to the Supabase setup guide: Supabase Setup Guide.

Supabase Configuration

To enable Webhooks, we need to create tables to manage customer data, set up essential RPC functions, and configure triggers to handle payments and subscriptions.
For detailed instructions, refer to the Supabase configuration guide: Supabase Configuration Guide.

This documentation is getting actively developed as we speak. Please check back later for more updates.

Payment Settings in `settings.js`

The settings.js file, located at /settings.js is the central configuration file for your StartupBolt application. This file contains various settings that control different aspects of your app, allowing for easy customization and management of your project's core parameters. It is important to update these configuration values as per your product or service.

PAYMENT_PROVIDER

Set this to LemonSqueezy:

const PAYMENT_PROVIDER = "LemonSqueezy";

NO_AUTH_CHECKOUT

Set this to true if you want to enable checkout for users who are not authenticated (i.e., not signed in).
Enabling checkout without authentication is usually recommended, as it reduces the number of steps users need to take to purchase your product. However, the decision is yours.

If you prefer to collect emails from users before they proceed to checkout, this can be a good strategy, though it may lower your conversion rate.

const NO_AUTH_CHECKOUT = true; // Enable checkout without authentication
// or
const NO_AUTH_CHECKOUT = false; // Require authentication for checkout

PLAN_DETAILS

This is where you configure the various payment plans.

   const PLAN_DETAILS = [
     {
       name: "Plan Name",
       price: 147,
       anchorPrice: 197,
       currency: "USD",
       pricePeriod: "monthly", // Leave empty for one-off payments
       description: "Product Description",
       features: [
         { name: "Feature 1", hasFeature: true },
         // ... more features
       ],
       payment: {
         id: "lemonsqueezy_variant_id",
         credits: 100, // Default is 100, can be changed
         rollover: false, // Credits are refilled, not rolled over
         mode: "payment", // Use "subscription" for recurring payments
         couponId: "lemonsqueezy_discount_code",
       },
       isPopular: true
     },
     // ... more plans
   ];

name: The name of the plan.
price: The actual price of the plan user will pay.
anchorPrice: The price of the plan before the discount.
currency: The currency of the plan shown in the pricing table.
pricePeriod: The period of the plan shown in the pricing table. Leave empty for one-off payments.
description: The description of the plan shown in the pricing table.
features: The features of the plan shown in the pricing table. hasFeature is a boolean value that shows in the pricing table if the feature is included in the plan or not.
payment: The payment details of the plan. Inside this, we have:
- id: The variant-id from LemonSqueezy that we copied in a previous step.
- Credits: Set to any number (default 100). Access to the product is granted if credits are greater than 0.
- Rollover:
  - false: Credits are refilled on payment, access lost if subscription lapses.
  - true: Unused credits carry over, access maintained until credits are depleted.
- Mode: Use "payment" for one-off payments, "subscription" for recurring payments. Only required for Stripe, but no problem if kept in Lemonsqueezy also.
- CouponId:
  - Create coupons in Store > Discounts (separate for test and live modes).
  - For more details, refer to the Coupons Documentation
isPopular: Set to true if you want to show this plan with a special badge in the pricing table.
You can also send the PLAN_DETAILS array as a prop to the PricingTable module. Feel free to refer to the PricingTable Module Documentation for more details.
Also, you can pass a single object from the PLAN_DETAILS array as a prop to the PayButton module. Feel free to refer to the PayButton Module Documentation for more details.

By following this guide, you'll have a comprehensive LemonSqueezy payment setup integrated into your application, covering both test and live environments.

Stripe Integration Credits and Rollover

LemonSqueezy Payment Setup Guide

Overview

Table of Contents

Set Up LemonSqueezy Account

Create Product

Test mode

Live Mode

Webhook and LemonSqueezy Environment Variables Setup

Test mode

Live Mode

Supabase Environment Variables Setup

Supabase Configuration

Payment Settings in settings.js

Payment Settings in `settings.js`