> For the complete documentation index, see [llms.txt](https://codemash.gitbook.io/codemash/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://codemash.gitbook.io/codemash/cloud/payments/integrations/providers/lemon-squeezy.md).

# Lemon Squeezy

Connect Lemon Squeezy to Payments — keys, webhook URL and signing secret.

Lemon Squeezy is a merchant of record for digital products and subscriptions. Norbix gets its webhook events (orders, refunds, subscriptions and subscription payments).

## Get your credentials

1. Sign in to the [Lemon Squeezy dashboard](https://app.lemonsqueezy.com/).
2. Open **Settings → Stores** and note the store id (a number such as `12345`).
3. Open **Settings → API**, create an API key and copy it (see [API requests](https://docs.lemonsqueezy.com/api/getting-started/requests)).
4. Save the integration in Cloud once (below) to get its **Webhook URL**.
5. Open **Settings → Webhooks → +**, paste the webhook URL as **Callback URL**, choose a **Signing secret** (any long random text) and the events (see [Webhooks](https://docs.lemonsqueezy.com/help/webhooks) and [signing requests](https://docs.lemonsqueezy.com/help/webhooks/signing-requests)). Type the same secret into **Webhook Signing Secret** in Cloud, type the API key again, and **Save**.

## Connect it in Cloud

**Where:** Payments → Integrations → **Add New Integration** → Lemon Squeezy → **Connect** · `/projects/<project>/payments/integrations/new/lemon-squeezy`

| Field                  | Required | What it does                                                                                                                               | Example                       |
| ---------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------- |
| Store ID               | yes      | Your Lemon Squeezy store.                                                                                                                  | `12345`                       |
| API Key                | yes      | Lets Norbix call Lemon Squeezy. Secret; encrypted on save and never shown again — type it again whenever you press **Save**.               | `eyJ0eXAiOiJKV1QiLCJhbGciOi…` |
| Webhook Signing Secret | yes      | Checks the `X-Signature` header of each call. Secret; encrypted on save and never shown again — type it again whenever you press **Save**. | `your-signing-secret`         |
| Test Mode              | no       | **Enable test mode** to use the test-mode data of the store.                                                                               | on                            |
| Integration Name       | yes      | The name in your integrations list.                                                                                                        | `Lemon Squeezy test store`    |

<figure><img src="https://712692422-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHy372bqsaex2cqS3ikhL%2Fuploads%2Fgit-blob-f54c21f924c6975813130e0a205bc608340e24d8%2Flemon-squeezy-form-1.png?alt=media" alt="New Lemon Squeezy Integration form filled with example values"><figcaption><p>The filled form (placeholder values).</p></figcaption></figure>

Press **Save**. The page turns into **Editing Lemon Squeezy integration** with the badges **ENABLED**, **NOT TESTED**, **NOT CONFIRMED**, the integration id (`int_3arT14C7MZ4pGvsSK1uTJj`) and the **Webhook URL** — `<Hub address>/v3/payments/webhooks/<account id>/<project id>/lemonsqueezy/<integration id>`; outside PROD it ends with `?env=<ENV>`. Copy it with its copy button and paste it at Lemon Squeezy (see **Get your credentials**). **Received webhooks** at the bottom lists every call Lemon Squeezy makes to it.

<figure><img src="https://712692422-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHy372bqsaex2cqS3ikhL%2Fuploads%2Fgit-blob-69e9448555f70b3473d88ca566c43bd98a725bdc%2Flemon-squeezy-saved-2.png?alt=media" alt="Editing Lemon Squeezy integration after Save: ENABLED, NOT TESTED, NOT CONFIRMED, the integration id and the Webhook URL"><figcaption><p>After save: the webhook URL to paste at Lemon Squeezy.</p></figcaption></figure>

Events Norbix accepts from Lemon Squeezy (pick them at Lemon Squeezy and in your [trigger](/codemash/cloud/payments/triggers/new.md)): `order_created`, `order_refunded`, `subscription_created`, `subscription_updated`, `subscription_cancelled`, `subscription_expired`, `subscription_payment_success`, `subscription_payment_failed`.

## Test and set as default

**Test integration** signs in to Lemon Squeezy with the API key. With the made-up key of this example it failed: *Lemon Squeezy authentication failed for integration int\_3arT14C7MZ4pGvsSK1uTJj: HTTP 401 Unauthorized*. See [Test an integration](/codemash/cloud/payments/integrations/test.md). Payments has no default integration — every enabled integration gets its own calls ([Default integration](/codemash/cloud/payments/integrations/set-default.md)).

## Common errors

| Message                                                     | Cause                                                                        | Fix                                                      |
| ----------------------------------------------------------- | ---------------------------------------------------------------------------- | -------------------------------------------------------- |
| Lemon Squeezy authentication failed … HTTP 401 Unauthorized | Wrong or deleted API key.                                                    | Create a new key, type it, **Save**, test again.         |
| **Received webhooks** shows **400**                         | The signing secret in Cloud is not the one set on the Lemon Squeezy webhook. | Type the same secret on both sides and **Save**.         |
| Required                                                    | A required field is empty — secrets count too on every save.                 | Fill the field; type every secret again before **Save**. |

## Do it from code

```ts
const { id } = await norbix.hub.payments.savePaymentsIntegration({
  integration: {
    provider: 'LemonSqueezy',
    integrationName: 'Lemon Squeezy store',
    isEnabled: true,
    storeId: '12345',
    apiKey: 'your-lemon-squeezy-api-key',
    webhookSigningSecret: 'your-signing-secret',
    isTestMode: false,
  } as any, // the TS type knows only the shared fields
});
console.log(id); // int_…
```

```sh
norbix hub payments integration save --integration '{"provider":"LemonSqueezy","integrationName":"Lemon Squeezy store","isEnabled":true,"storeId":"12345","apiKey":"your-lemon-squeezy-api-key","webhookSigningSecret":"your-signing-secret","isTestMode":false}'
```

The client setup is on the [Payments page](/codemash/cloud/payments.md#use-it-from-code). API: [Save Payments Integration](/codemash/api-reference/payments/integrations/save-payments-integration.md)