Lemon Squeezy

https://docs.lemonsqueezy.com/help
Admin
Lemon Squeezy is an all-in-one e-commerce platform for running SaaS and software businesses,...
Tokens:59,059
Snippets:644
Trust Score:9.4
Update:3 days ago
Show doc for...
Tokens:
Raw
### Example checkout link

Source: https://docs.lemonsqueezy.com/help/checkout/prefilled-checkout-fields

Example of a real checkout link with a store name and variant ID.

```text
https://my-store.lemonsqueezy.com/checkout/buy/d1f120fd-5adc-4fff-8915-cce713d29427

```

--------------------------------

### Setup event handler with LemonSqueezy.Setup

Source: https://docs.lemonsqueezy.com/help/lemonjs/handling-events

Use this snippet to listen to all Lemon.js overlay events. The eventHandler callback receives an event object; check event.event to determine which event occurred.

```javascript
LemonSqueezy.Setup({
  eventHandler: (event) => {
    // Do whatever you want with this event data
  }
})

```

--------------------------------

### URL with order_id, email, and total placeholders

Source: https://docs.lemonsqueezy.com/help/products/button-link-variables

Example URL using multiple supported placeholders: order_id, email, and total. These placeholders are replaced with real order values when a customer purchases your product.

```text
https://example.com/welcome?order_id=[order_id]&email=[email]&total=[total]

```

--------------------------------

### Lemon.js Build method to add affiliate tracking parameter

Source: https://docs.lemonsqueezy.com/help/affiliates-for-merchants/getting-referrals

JavaScript example using LemonSqueezy.Url.Build to construct a checkout URL with the affiliate tracking parameter. The method appends '?aff_ref=1234' to the URL.

```javascript
let url = 'https://my-store.lemonsqueezy.com/checkout/buy/0a841cf5-4cc2-4bbb-ae5d-9529d97deec6'
url = LemonSqueezy.Url.Build(url)
// https://my-store.lemonsqueezy.com/checkout/buy/0a841cf5-4cc2-4bbb-ae5d-9529d97deec6?aff_ref=1234
```

--------------------------------

### Example event object with event.event

Source: https://docs.lemonsqueezy.com/help/lemonjs/handling-events

Shows the structure of an event object. The event.event property contains the event name, e.g., "PaymentMethodUpdate.Mounted".

```json
{
  event: "PaymentMethodUpdate.Mounted"
}

```

--------------------------------

### Verify webhook signature in Node.js

Source: https://docs.lemonsqueezy.com/help/webhooks/signing-requests

Node.js example for verifying a Lemon Squeezy webhook signature. It computes an HMAC SHA-256 hex digest of the raw request body using the signing secret and compares it with the X-Signature header using crypto.timingSafeEqual. Throws an error if the signatures do not match.

```javascript
import crypto from "node:crypto";
 
const secret = 'SIGNING_SECRET';
const hmac = crypto.createHmac('sha256', secret);
const digest = Buffer.from(hmac.update(request.rawBody).digest('hex'), 'utf8');
const signature = Buffer.from(request.get('X-Signature') || '', 'utf8');
 
if (!crypto.timingSafeEqual(digest, signature)) {
    throw new Error('Invalid signature.');
}

```

--------------------------------

### window.LemonSqueezy.Setup(options)

Source: https://docs.lemonsqueezy.com/help/lemonjs/using-with-frameworks-libraries

Initialises Lemon.js on the page by providing an event handler that receives Lemon.js events.

```APIDOC
## [JS] window.LemonSqueezy.Setup(options)

### Description
Initialises Lemon.js on your page. It accepts an options object with a single property, eventHandler, which is a function that will be called when Lemon.js emits an event.

### Method
Setup

### Endpoint
window.LemonSqueezy.Setup(options)

### Parameters
#### Request Body
- **options** (object) - Required - An object with a single property, eventHandler.
  - **eventHandler** (function) - Required - A function that will be called when Lemon.js emits an event. It receives an event object with a single property `event` (string).

### Request Example
```typescript
window.LemonSqueezy.Setup({
  eventHandler: (event) => {
    console.log(event.event);
  }
})
```

### Response
#### Success Response
No explicit response is documented.

```

--------------------------------

### LemonSqueezy.Setup(options)

Source: https://docs.lemonsqueezy.com/help/lemonjs/methods

Initializes Lemon.js on your page with optional event handler.

```APIDOC
## LemonSqueezy.Setup(options)

### Description
Initializes Lemon.js on your page. Accepts an options object with an optional eventHandler callback.

### Method
Setup

### Parameters
#### Request Body
- **options** (object) - Required - An object containing setup options.
  - **eventHandler** (function) - Optional - Callback function that receives event data.

### Request Example
```javascript
LemonSqueezy.Setup({
  eventHandler: (event) => {
    // Do whatever you want with this event data
  }
})
```

### Response
No response value is returned.
```

--------------------------------

### order_created

Source: https://docs.lemonsqueezy.com/help/webhooks/example-payloads

Returns an Order object when an order is created. This is a webhook event payload example.

```APIDOC
## order_created

### Description
Returns an Order object when an order is created.

### Event Name
order_created

### Payload Example
```json
{
  "meta": {
    "event_name": "order_created"
  },
  "data": {
    "type": "orders",
    "id": "1",
    "attributes": {
      "store_id": 1,
      "customer_id": 1,
      "identifier": "89b36d62-4f5c-4353-853f-0c769d0535c8",
      "order_number": 1,
      "user_name": "John Doe",
      "user_email": "johndoe@example.com",
      "currency": "EUR",
      "currency_rate": "1.08405",
      "subtotal": 1499.985,
      "discount_total": 0,
      "tax": 359.775,
      "total": 1859.76,
      "subtotal_usd": 1626,
      "discount_total_usd": 0,
      "tax_usd": 390,
      "total_usd": 2016,
      "tax_name": "ALV",
      "tax_rate": "24.00",
      "status": "paid",
      "status_formatted": "Paid",
      "refunded": null,
      "refunded_at": null,
      "subtotal_formatted": "€14.99",
      "discount_total_formatted": "€0.00",
      "tax_formatted": "€3.59",
      "total_formatted": "€18.59",
      "first_order_item": {
        "order_id": 1,
        "product_id": 1,
        "variant_id": 1,
        "product_name": "Product One",
        "variant_name": "Default",
        "price": 1500,
        "created_at": "2023-01-17T12:26:23.000000Z",
        "updated_at": "2023-01-17T12:26:23.000000Z",
        "test_mode": false
      },
      "urls": {
        "receipt": "https://app.lemonsqueezy.com/my-orders/89b36d62-4f5c-4353-853f-0c769d0535c8?signature=8847fff02e1bfb0c7c43ff1cdf1b1657a8eed2029413692663b86859208c9f42"
      },
      "created_at": "2023-01-17T12:26:23.000000Z",
      "updated_at": "2023-01-17T12:26:23.000000Z",
      "test_mode": false
    },
    "relationships": {
      "store": {
        "links": {
          "related": "https://api.lemonsqueezy.com/v1/orders/1/store",
          "self": "https://api.lemonsqueezy.com/v1/orders/1/relationships/store"
        }
      },
      "customer": {
        "links": {
          "related": "https://api.lemonsqueezy.com/v1/orders/1/customer",
          "self": "https://api.lemonsqueezy.com/v1/orders/1/relationships/customer"
        }
      },
      "order-items": {
        "links": {
          "related": "https://api.lemonsqueezy.com/v1/orders/1/order-items",
          "self": "https://api.lemonsqueezy.com/v1/orders/1/relationships/order-items"
        }
      },
      "subscriptions": {
        "links": {
          "related": "https://api.lemonsqueezy.com/v1/orders/1/subscriptions",
          "self": "https://api.lemonsqueezy.com/v1/orders/1/relationships/subscriptions"
        }
      },
      "license-keys": {
        "links": {
          "related": "https://api.lemonsqueezy.com/v1/orders/1/license-keys",
          "self": "https://api.lemonsqueezy.com/v1/orders/1/relationships/license-keys"
        }
      },
      "discount-redemptions": {
        "links": {
          "related": "https://api.lemonsqueezy.com/v1/orders/1/discount-redemptions",
          "self": "https://api.lemonsqueezy.com/v1/orders/1/relationships/discount-redemptions"
        }
      }
    },
    "links": {
      "self": "https://api.lemonsqueezy.com/v1/orders/1"
    }
  }
}
```
```

--------------------------------

### Checkout Object response with URL

Source: https://docs.lemonsqueezy.com/help/lemonjs/opening-overlays

Example response from the Checkouts API containing a custom checkout URL in the data.attributes.url field.

```json
{
  ...
  "data": {
    "type": "checkouts",
    "id": "...",
    "attributes": {
      ...
      "url": "https://my-store.lemonsqueezy.com/checkout/custom/..."
    },
    ...
  }
}
```

--------------------------------

### LemonSqueezy.Setup eventHandler callback

Source: https://docs.lemonsqueezy.com/help/lemonjs/methods

Callback function passed to the eventHandler option of LemonSqueezy.Setup(). Receives event data for custom handling.

```javascript
eventHandler: (event) => {
  // Do whatever you want with this event data
}
```

--------------------------------

### Subscription response with update_payment_method URL

Source: https://docs.lemonsqueezy.com/help/lemonjs/opening-overlays

Example response from the Subscriptions API containing a customer-facing signed URL for updating payment details.

```json
{
  {...},
  "data": {
    {...},
    "attributes": {
      ...
      "urls": {
        "update_payment_method": "https://my-store.lemonsqueezy.com/subscription/.../payment-details...",
        ...
      },
      ...
    },
    {...}
  }
}
```

--------------------------------

### Checkout.Success event with order data

Source: https://docs.lemonsqueezy.com/help/lemonjs/handling-events

Example of a Checkout.Success event object. The event.data contains an Order object with type, id, and attributes.

```json
{
  "event": "Checkout.Success",
  "data": {
    "type": "orders",
    "id": "1",
    "attributes": {
      "store_id": 1,
      "customer_id": 1,
      ...
    },
    ...
  }
}

```

--------------------------------

### Create checkout with prefilled data via API

Source: https://docs.lemonsqueezy.com/help/checkout/prefilled-checkout-fields

Create a checkout via the Lemon Squeezy API with prefilled customer data in the checkout_data JSON object. Replace {api_key} with your API key and fill in the relationships object.

```bash
curl -X "POST" "https://api.lemonsqueezy.com/v1/checkouts" \
     -H 'Accept: application/vnd.api+json' \
     -H 'Content-Type: application/vnd.api+json' \
     -H 'Authorization: Bearer {api_key}' \
     -d '{
  "data": {
    "type": "checkouts",
    "attributes": {
      "checkout_data": {
        "email": "johndoe@example.com",
        "name": "John Doe"
      }
    },
    "relationships": {
      ...
    }
  }
}'

```

--------------------------------

### LemonSqueezy.Affiliate.GetId method

Source: https://docs.lemonsqueezy.com/help/affiliates-for-merchants/getting-referrals

JavaScript example showing how to retrieve the affiliate tracking ID using the GetId method. Useful for backend custom checkout URL construction.

```javascript
LemonSqueezy.Affiliate.GetId()
```

--------------------------------

### Webhook POST Request

Source: https://docs.lemonsqueezy.com/help/webhooks/webhook-requests

Describes the incoming webhook request sent by Lemon Squeezy to the configured URL when an event occurs. It includes the HTTP method, headers, and example body.

```APIDOC
## [POST] Webhook URL

### Description
When a webhook event occurs, Lemon Squeezy sends a POST request to the configured webhook URL with event-specific JSON data. The receiving endpoint must return a 200 response to indicate successful capture; otherwise, the request is retried up to three more times with exponential backoff.

### Method
POST

### Endpoint
[Configured webhook URL]

### Headers
- **Content-Type** (string) - Required - Set to `application/json`.
- **X-Event-Name** (string) - Required - The name of the event that triggered the webhook (e.g., `order_created`).
- **X-Signature** (string) - Required - The request signature for verification.

### Request Body
The body is a JSON:API resource object related to the event (e.g., an order object for order events). It includes a `meta` object with `event_name` and optional `custom_data`, and a `data` object with the resource details.

### Request Example
```json
{
  "meta": {
    "event_name": "order_created",
    "custom_data": {
      "customer_id": 25
    }
  },
  "data": {
    "type": "orders",
    "id": "1",
    "attributes": {
      "store_id": 1,
      "customer_id": 1,
      "identifier": "104e18a2-d755-4d4b-80c4-a6c1dcbe1c10",
      "order_number": 1,
      "user_name": "John Doe",
      "user_email": "johndoe@example.com",
      "currency": "USD",
      "currency_rate": "1.0000",
      "subtotal": 999,
      "discount_total": 0,
      "tax": 200,
      "total": 1199,
      "subtotal_usd": 999,
      "discount_total_usd": 0,
      "tax_usd": 200,
      "total_usd": 1199,
      "tax_name": "VAT",
      "tax_rate": "20.00",
      "status": "paid",
      "status_formatted": "Paid",
      "refunded": false,
      "refunded_at": null,
      "subtotal_formatted": "$9.99",
      "discount_total_formatted": "$0.00",
      "tax_formatted": "$2.00",
      "total_formatted": "$11.99",
      "first_order_item": {
        "id": 1,
        "order_id": 1,
        "product_id": 1,
        "variant_id": 1,
        "product_name": "Test Limited License for 2 years",
        "variant_name": "Default",
        "price": 1199,
        "created_at": "2021-08-17T09:45:53.000000Z",
        "updated_at": "2021-08-17T09:45:53.000000Z",
        "deleted_at": null,
        "test_mode": false
      },
      "urls": {
        "receipt": "https://app.lemonsqueezy.com/my-orders/104e18a2-d755-4d4b-80c4-a6c1dcbe1c10?signature=8847fff02e1bfb0c7c43ff1cdf1b1657a8eed2029413692663b86859208c9f42"
      },
      "created_at": "2021-08-17T09:45:53.000000Z",
      "updated_at": "2021-08-17T09:45:53.000000Z"
    },
    "relationships": {
      "store": {
        "links": {
          "related": "https://api.lemonsqueezy.com/v1/orders/1/store",
          "self": "https://api.lemonsqueezy.com/v1/orders/1/relationships/store"
        }
      },
      "customer": {
        "links": {
          "related": "https://api.lemonsqueezy.com/v1/orders/1/customer",
          "self": "https://api.lemonsqueezy.com/v1/orders/1/relationships/customer"
        }
      },
      "order-items": {
        "links": {
          "related": "https://api.lemonsqueezy.com/v1/orders/1/order-items",
          "self": "https://api.lemonsqueezy.com/v1/orders/1/relationships/order-items"
        }
      },
      "subscriptions": {
        "links": {
          "related": "https://api.lemonsqueezy.com/v1/orders/1/subscriptions",
          "self": "https://api.lemonsqueezy.com/v1/orders/1/relationships/subscriptions"
        }
      },
      "license-keys": {
        "links": {
          "related": "https://api.lemonsqueezy.com/v1/orders/1/license-keys",
          "self": "https://api.lemonsqueezy.com/v1/orders/1/relationships/license-keys"
        }
      },
      "discount-redemptions": {
        "links": {
          "related": "https://api.lemonsqueezy.com/v1/orders/1/discount-redemptions",
          "self": "https://api.lemonsqueezy.com/v1/orders/1/relationships/discount-redemptions"
        }
      }
    },
    "links": {
      "self": "https://api.lemonsqueezy.com/v1/orders/1"
    }
  }
}
```

### Response
#### Success Response (200)
Return a `200` response to indicate that the webhook was successfully captured. Any other status will trigger retries.

#### Response Example
HTTP/1.1 200 OK

```

--------------------------------

### window.createLemonSqueezy()

Source: https://docs.lemonsqueezy.com/help/lemonjs/using-with-frameworks-libraries

Manually re-initializes the Lemon.js button listeners after the component mounts.

```APIDOC
## [JS] window.createLemonSqueezy()

### Description
Manually calls `window.createLemonSqueezy()` to re-initialize the button listeners after Lemon.js has loaded, especially in scenarios where the component mounts after the initial load. This method can be called multiple times as needed.

### Method
createLemonSqueezy

### Endpoint
window.createLemonSqueezy()

### Parameters
No parameters documented.

### Request Example
```javascript
window.createLemonSqueezy();
```

### Response
#### Success Response
No explicit response is documented.

```

--------------------------------

### window.LemonSqueezy.Affiliate.Build(url)

Source: https://docs.lemonsqueezy.com/help/lemonjs/using-with-frameworks-libraries

Appends the affiliate tracking parameter to a given URL and returns the modified URL.

```APIDOC
## [JS] window.LemonSqueezy.Affiliate.Build(url)

### Description
Appends the affiliate tracking parameter to the given URL.

### Method
Build

### Endpoint
window.LemonSqueezy.Affiliate.Build(url)

### Parameters
#### Path Parameters
- **url** (string) - Required - The URL to append the affiliate tracking parameter to.

### Request Example
```typescript
const newUrl = window.LemonSqueezy.Affiliate.Build('https://example.com');
```

### Response
#### Success Response
- Returns a string with the affiliate tracking parameter appended.

```

--------------------------------

### LemonSqueezy.Url.Open(url)

Source: https://docs.lemonsqueezy.com/help/lemonjs/methods

Opens a Lemon Squeezy overlay URL.

```APIDOC
## LemonSqueezy.Url.Open(url)

### Description
Opens a given Lemon Squeezy URL, typically Checkout or Payment Details Update overlays.

### Method
Open

### Parameters
#### Path Parameters
- **url** (string) - Required - The Lemon Squeezy URL to open.

### Response
No response value is returned.
```

--------------------------------

### Webhook payload with custom_data

Source: https://docs.lemonsqueezy.com/help/checkout/passing-custom-data

Example webhook payload showing the custom_data object inside the meta field. This appears in Order, Subscription, and License Key webhook events when custom data was passed to the checkout.

```json
{
  "meta": {
    "event_name": "order_created",
    "custom_data": {
      "user_id": "123",
      "campaign_id": "abc"
    }
  },
  ...
}
```
Tokens:
Raw