Documentation
Billing

Lemonsqueezy

Create an api key

After you have created your account and a store for Lemonsqueezy, you will need to create a new API key. You can do this by going to the API page in the settings and clicking on the plus button. You will need to give your API key a name and then click on the "Create" button. Once you have created your API key, you will need to copy the API key to use it in the setup of the integration when running the CLI.

Add environment variables

To use the Lemonsqueezy integration, you need to define the following environment variables to your .env.local as well as your production environment:

LEMONSQUEEZY_API_KEY="" # Your Lemonsqueezy API key
LEMONSQUEEZY_SIGNING_SECRET="" # Your Lemonsqueezy webhook signing secret
LEMONSQUEEZY_STORE_ID="" # Your Lemonsqueezy store ID (can be found under Settings > Stores next to your store url, e.g #12345)

Create products

For your users to choose from the available subscription plans, you need to create those Products first on the Products page. You can create as many products as you want, but you will need to create at least one product for the integration to work.

Create as many plans as you like. Each plan has to be created as a Subscription and you can choose the interval of the subscription.

Create a product

Subscription interval

To offer multiple intervals for each plan, you can use the Variant feature of Lemonsqueezy. Just create one variant for each interval you want to offer. supastarter will automatically output the variants for you then in the UI.

To offer a free trial, you can set the Trial period to the number of days you want to offer the trial for.

Trial period

Create webhook

To sync the current subscription status and other information to your database, you need to set up a webhook.

The webhook code comes ready to use with supastarter, you just have to create the webhook in Lemonsqueezy and insert the URL for your project.

To configure a new webhook, go to the Webhooks page in the lemonsqueezy settings and click the Plus button.

You will have to enter a Signing secret which you can get by running the following command in your terminal:

openssl rand -base64 32

Copy the generated string and paste it into the Signing secret field.

You also need to add this secret to your environment variables:

LEMONSQUEEZY_WEBHOOK_SECRET=your-signing-secret

Then select all events and click on the Save webhook button.

Create a webhook

To get the URL for the webhook, read the next section.

Local development

If you want to test the webhook locally, you can use ngrok to create a tunnel to your local machine. Ngrok will then give you a URL that you can use to test the webhook locally.

To do so, install ngrok and run it with the following command (while your supastarter development server is running):

ngrok http 3000

ngrok

This will give you a URL (see the Forwarding output) that you can use to create a webhook in Lemonsqueezy. Just use that url and add /api/webhooks/lemonsqueezy to it.

Production / preview deployment

When you have already deployed a version of your project, you can use the actual URL to create the webhook with. This will be necessary for a production version your app later anyway.

Make sure you have a deployed version that has the LEMONSQUEEZY_WEBHOOK_SECRET environment variable set.

Then you can use the URL of your deployed app and add /api/webhooks/lemonsqueezy to it.

Example URL: https://your-app.com/api/webhooks/lemonsqueezy

Set currency in your app

Lastly you need to configure the currency that you want to use for your products. Since Lemonsqueezy only supports one currency per shop, this will be the same for all languages in your app.

You can do this by setting the numberFormats[<lang>].currency.style variables in the apps/web/i18n.config.ts file.

export default defineI18nConfig(() => ({
  // ...
  numberFormats: {
    en: {
      currency: {
        style: "currency",
        currency: "USD",
        notation: "standard",
      },
      // ...
    },
 
    // 'de' and other languages...
  },
}));

On this page