Lemon Squeezy

https://docs.lemonsqueezy.com/guides/developer-guide
Admin
Lemon Squeezy is a digital product platform that enables developers to integrate payments,...
Tokens:14,592
Snippets:124
Trust Score:9.4
Update:4 months ago
Show doc for...
Tokens:
Raw
### Example Subscription Created Webhook Data

Source: https://docs.lemonsqueezy.com/guides/developer-guide/webhooks

This is an example of the JSON data received for a 'subscription_created' webhook event. It includes details about the subscription and related objects.

```json
{
  "meta": {
    "event_name": "subscription_created"
  },
  "type": "subscriptions",
  "id": "1",
  "attributes": {
    "store_id": 1,
    "customer_id": 1,
    "order_id": 1,
    "order_item_id": 1,
    "product_id": 1,
    "variant_id": 1,
    "product_name": "Lemonade",
    "variant_name": "Citrus Blast",
    "user_name": "John Doe",
    "user_email": "johndoe@example.com",
    "status": "active",
    "status_formatted": "Active",
    "card_brand": "visa",
    "card_last_four": "42424",
    "payment_processor": "stripe",
    "pause": null,
    "cancelled": false,
    "trial_ends_at": null,
    "billing_anchor": 12,
    "first_subscription_item": {
      "id": 1,
      "subscription_id": 1,
      "price_id": 1,
      "quantity": 5,
      "created_at": "2021-08-11T13:47:28.000000Z",
      "updated_at": "2021-08-11T13:47:28.000000Z"
    },
    "urls": {
      "update_payment_method": "https://my-store.lemonsqueezy.com/subscription/1/payment-details?expires=1666869343&signature=9985e3bf9007840aeb3951412be475abc17439c449c1af3e56e08e45e1345413",
      "customer_portal": "https://my-store.lemonsqueezy.com/billing?expires=1666869343&signature=82ae290ceac8edd4190c82825dd73a8743346d894a8ddbc4898b97eb96d105a5",
      "customer_portal_update_subscription": "https://my-store.lemonsqueezy.com/billing/1/update?expires=1666869343&signature=e4fabc7ee703664d644bba9e79a9cd3dd00622308b335f3c166787f0b18999f2"
    },
    "renews_at": "2022-11-12T00:00:00.000000Z",
    "ends_at": null,
    "created_at": "2021-08-11T13:47:27.000000Z",
    "updated_at": "2021-08-11T13:54:19.000000Z",
    "test_mode": false
  }
}
```

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

### Example Webhook Data With Custom Data

Source: https://docs.lemonsqueezy.com/guides/developer-guide/webhooks

This example shows how custom data, added during checkout, appears within the 'meta.custom_data' field of a webhook event.

```json
{
  "meta": {
    "event_name": "subscription_created",
    "custom_data": {
      "user_id": 123
    }
  },
  "data": {
    "type": "subscriptions",
    ...
  }
}
```

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

### Setup Event Handler for Lemon.js

Source: https://docs.lemonsqueezy.com/guides/developer-guide/lemonjs

Configure an event handler using LemonSqueezy.Setup() to listen for events during the overlay form flow, such as 'PaymentMethodUpdate.Updated'.

```javascript
LemonSqueezy.Setup({
  eventHandler: (data) => {
    if (data.event == "PaymentMethodUpdate.Updated") {
      // Do something when the payment method has been updated
    }
  }
});

```

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

### Example API Response for an Order

Source: https://docs.lemonsqueezy.com/guides/developer-guide/getting-started

This is an example of a JSON response for a specific order, illustrating the structure of order data, attributes, relationships, and included resources as per the JSON:API specification.

```json
{
  "jsonapi": {
    "version": "1.0"
  },
  "links": {
    "self": "https://api.lemonsqueezy.com/v1/orders/1"
  },
  "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": "Lemonade - 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/subscriptions/1/customer",
          "self": "https://api.lemonsqueezy.com/v1/subscriptions/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"
    }
  }
}
```

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

### Create Checkout API Request

Source: https://docs.lemonsqueezy.com/guides/developer-guide/taking-payments

Example of a POST request to the Lemon Squeezy API to create a checkout, including authorization and content type headers.

```http
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 '{...}'
```

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

### Get Subscription Item Details via API

Source: https://docs.lemonsqueezy.com/guides/developer-guide/usage-based-billing

Send a GET request to the Subscription item endpoint to retrieve the current quantity and other details of a subscription.

```http
GET https://api.lemonsqueezy.com/v1/subscription-items/1
```

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

### GET Subscription Item Current Usage

Source: https://docs.lemonsqueezy.com/guides/developer-guide/usage-based-billing

Make a GET request to this endpoint to retrieve the current usage of a specific subscription item. The response includes metadata about the billing period and the current quantity.

```http
GET https://api.lemonsqueezy.com/v1/subscription-items/1/current-usage
```

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

### Get Subscription Item

Source: https://docs.lemonsqueezy.com/guides/developer-guide/usage-based-billing

Retrieves the details of a specific subscription item, including its current quantity.

```APIDOC
## GET /v1/subscription-items/{id}

### Description
Retrieves a specific subscription item by its ID.

### Method
GET

### Endpoint
https://api.lemonsqueezy.com/v1/subscription-items/{id}

### Parameters
#### Path Parameters
- **id** (integer) - Required - The ID of the subscription item to retrieve.

### Response
#### Success Response (200)
- **type** (string) - The type of the resource, e.g., "subscription-items".
- **id** (string) - The ID of the subscription item.
- **attributes** (object) - The attributes of the subscription item.
  - **subscription_id** (integer) - The ID of the associated subscription.
  - **price_id** (integer) - The ID of the associated price.
  - **quantity** (integer) - The current quantity of the subscription item.
  - **is_usage_based** (boolean) - Indicates if the item is usage-based.
  - **created_at** (string) - The timestamp when the subscription item was created.
  - **updated_at** (string) - The timestamp when the subscription item was last updated.

### Response Example
```json
{
  "type": "subscription-items",
  "id": "1",
  "attributes": {
    "subscription_id": 1,
    "price_id": 1,
    "quantity": 1,
    "is_usage_based": false,
    "created_at": "2023-07-18T12:16:24.000000Z",
    "updated_at": "2023-07-18T12:16:24.000000Z"
  }
}
```
```

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

### Request New Customer Portal URL

Source: https://docs.lemonsqueezy.com/guides/developer-guide/customer-portal

Use the Retrieve a subscription endpoint to get a new customer portal URL. This is recommended when a user clicks a Billing button.

```javascript
app.get('/api/subscriptions', (req, res) => {
  // Using @lemonsqueezy/lemonsqueezy.js
  lemonSqueezySetup({ apiKey: 'api_key' });
  const { data } = await getSubscription('subscription_id');
  res.json({ url: data['attributes']['urls']['customer_portal'] })
})

```

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

### Query Subscription Item Usage

Source: https://docs.lemonsqueezy.com/guides/developer-guide/usage-based-billing

Retrieve the current billable usage for a specific subscription item by making a GET request to its dedicated endpoint. The response includes metadata about the usage period and the total quantity recorded.

```APIDOC
## GET /v1/subscription-items/{id}/current-usage

### Description
Retrieves the real-time billable usage for a given subscription item.

### Method
GET

### Endpoint
/v1/subscription-items/{id}/current-usage

### Parameters
#### Path Parameters
- **id** (integer) - Required - The ID of the subscription item.

### Response
#### Success Response (200)
- **jsonapi** (object) - API JSON:API object.
  - **version** (string) - The JSON:API version.
- **meta** (object) - Metadata about the usage.
  - **period_start** (string) - The start date and time of the current usage period (ISO 8601 format).
  - **period_end** (string) - The end date and time of the current usage period (ISO 8601 format).
  - **quantity** (integer) - The total recorded quantity for the current billing period.
  - **interval_unit** (string) - The unit of the billing interval (e.g., "month").
  - **interval_quantity** (integer) - The quantity of the interval unit (e.g., 1 for monthly billing).

### Response Example
```json
{
  "jsonapi": {
    "version": "1.0"
  },
  "meta": {
    "period_start": "2023-08-10T13:08:16+00:00",
    "period_end": "2023-09-10T13:03:16+00:00",
    "quantity": 5,
    "interval_unit": "month",
    "interval_quantity": 1
  }
}
```
```

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

### Subscription Item Current Usage Response

Source: https://docs.lemonsqueezy.com/guides/developer-guide/usage-based-billing

The API response provides details on the billing period start and end, the current quantity of usage, and interval information. The 'quantity' value is updated each time a usage record is sent.

```json
{
  "jsonapi": {
    "version": "1.0"
  },
  "meta": {
    "period_start": "2023-08-10T13:08:16+00:00",
    "period_end": "2023-09-10T13:03:16+00:00",
    "quantity": 5,
    "interval_unit": "month",
    "interval_quantity": 1
  }
}
```

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

### Create a New Webhook via API

Source: https://docs.lemonsqueezy.com/guides/developer-guide/webhooks

Use this POST request to create a new webhook. Specify the URL, events to subscribe to, and a signing secret. Ensure you include the store ID in the relationships.

```bash
POST https://api.lemonsqueezy.com/v1/webhooks

```

```json
{
  "data": {
    "type": "webhooks",
    "attributes": {
      "url": "https://example.com/webhooks/",
      "events": [
        "order_created",
        "subscription_created",
        "subscription_updated",
        "subscription_expired"
      ],
      "secret": "SIGNING_SECRET"
    },
    "relationships": {
      "store": {
        "data": {
          "type": "stores",
          "id": "1"
        }
      }
    }
  }
}

```

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

### Create Buy Buttons with CSS Class

Source: https://docs.lemonsqueezy.com/guides/developer-guide/lemonjs

Add the 'lemonsqueezy-button' CSS class to your links to automatically open checkout URLs in an overlay.

```html
<a class="lemonsqueezy-button" href="https://[STORE].lemonsqueezy.com/checkout/buy/...">
    Buy this
</a>

```

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

### Create a Checkout URL using the API

Source: https://docs.lemonsqueezy.com/guides/developer-guide/taking-payments

Use this cURL command to create a checkout for a specified variant via the Lemon Squeezy API. Ensure you replace placeholder IDs with your actual store and variant IDs, and your API key.

```curl
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", 
    "relationships": { 
      "store": { 
        "data": { 
          "type": "stores", 
          "id": "2" 
        } 
      }, 
      "variant": { 
        "data": { 
          "type": "variants", 
          "id": "2" 
        } 
      } 
    } 
  } 
}'
```

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

### Open Checkout Overlay with Lemon.js

Source: https://docs.lemonsqueezy.com/guides/developer-guide/taking-payments

Use Lemon.js to open a checkout URL in an overlay. Ensure the Lemon.js script is included on your page.

```javascript
const checkoutUrl = response['data']['attributes']['url'];
LemonSqueezy.Url.Open(checkoutUrl);
```

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

### Set Quantity at Checkout via URL

Source: https://docs.lemonsqueezy.com/guides/developer-guide/usage-based-billing

Append the 'quantity' query parameter to a product's share URL to set a specific quantity at checkout. Defaults to 1 if not specified.

```url
https://[STORE].lemonsqueezy.com/checkout/buy/[VARIANT_ID]?quantity=100
```

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

### Pre-fill Checkout Fields via URL Parameters

Source: https://docs.lemonsqueezy.com/guides/developer-guide/taking-payments

Append query string parameters to your checkout URL to pre-populate fields like email, name, and billing address.

```url
https://[STORE].lemonsqueezy.com/checkout/buy/[VARIANT_ID]
?checkout[email]=johndoe@example.com
&checkout[name]=John Doe
&checkout[billing_address][country]=US
&checkout[billing_address][state]=NY
&checkout[billing_address][zip]=10121
&checkout[tax_number]=123456789
&checkout[discount_code]=10PERCENTOFF
```

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

### Open Update Payment Method Overlay

Source: https://docs.lemonsqueezy.com/guides/developer-guide/lemonjs

Load update payment method URLs in an overlay using Lemon.js for a seamless in-app experience.

```javascript
const updatePaymentMethodUrl = 'https://app.lemonsqueezy.com/subscription/.../payment-details...';
LemonSqueezy.Url.Open(updatePaymentMethodUrl);

```

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

### Create Checkout with Quantity

Source: https://docs.lemonsqueezy.com/guides/developer-guide/usage-based-billing

Allows setting a specific quantity for a product at checkout. If not specified, it defaults to 1. The total charged is based on pricing and quantity.

```APIDOC
## POST /v1/checkouts

### Description
Creates a checkout session with a specified quantity for a variant.

### Method
POST

### Endpoint
https://api.lemonsqueezy.com/v1/checkouts

### Parameters
#### Request Body
- **data** (object) - Required - The checkout data.
  - **type** (string) - Required - Must be "checkouts".
  - **attributes** (object) - Required - Attributes for the checkout.
    - **checkout_data** (object) - Required - Data specific to the checkout.
      - **variant_quantities** (array) - Required - An array of objects, each specifying a variant ID and its quantity.
        - **variant_id** (integer) - Required - The ID of the variant.
        - **quantity** (integer) - Required - The quantity of the variant.
  - **relationships** (object) - Required - Relationships for the checkout.
    - **store** (object) - Required - The store relationship.
      - **data** (object) - Required - Data for the store relationship.
        - **type** (string) - Required - Must be "stores".
        - **id** (string) - Required - The ID of the store.
    - **variant** (object) - Required - The variant relationship.
      - **data** (object) - Required - Data for the variant relationship.
        - **type** (string) - Required - Must be "variants".
        - **id** (string) - Required - The ID of the variant.

### Request Example
```json
{
  "data": {
    "type": "checkouts",
    "attributes": {
      "checkout_data": {
        "variant_quantities": [
          {
            "variant_id": 1,
            "quantity": 10
          }
        ]
      }
    },
    "relationships": {
      "store": {
        "data": {
          "type": "stores",
          "id": "1"
        }
      },
      "variant": {
        "data": {
          "type": "variants",
          "id": "1"
        }
      }
    }
  }
}
```
```

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

### Open Checkout URLs with JavaScript

Source: https://docs.lemonsqueezy.com/guides/developer-guide/lemonjs

Use the LemonSqueezy.Url.Open() method to programmatically open checkout URLs, useful for dynamically generated links.

```javascript
const checkoutUrl = 'https://[STORE].lemonsqueezy.com/checkout/custom/...';
LemonSqueezy.Url.Open(checkoutUrl);

```

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

### Override Product Details for Checkout

Source: https://docs.lemonsqueezy.com/guides/developer-guide/taking-payments

Customize product attributes like name, description, and redirect URL for API-created checkouts using the `product_options` object. This allows for a tailored checkout experience.

```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": { \
      "product_options": { \
        "name": "Unique subscription for Dave", \
        "redirect_url": "https://myapp.com/welcome/?user=dave123", \
        "receipt_button_text": "Go to your account" \
      } \
    }, \
    "relationships": { \
      ... \
    } \
  } \
}'
```

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

### Billing Button HTML

Source: https://docs.lemonsqueezy.com/guides/developer-guide/customer-portal

This HTML and JavaScript snippet shows how to handle a button click to fetch a customer portal URL and redirect the user.

```html
<!-- billing.html -->
<script>
function handleClick(e) {
  e.preventDefault()
 
  fetch('/api/subscriptions')
  .then(response => response.json())
  .then(res => {
    window.location = res.url
  })
}
</script>
 
<button onclick="handleClick()">Manage your subscription</button>

```

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

### Create a new webhook

Source: https://docs.lemonsqueezy.com/guides/developer-guide/webhooks

This endpoint allows you to create a new webhook subscription. You need to specify the URL where webhook events should be sent, the types of events to subscribe to, and a signing secret for security. A store ID is also required to associate the webhook with a specific store.

```APIDOC
## POST /v1/webhooks

### Description
Creates a new webhook subscription to receive event notifications.

### Method
POST

### Endpoint
https://api.lemonsqueezy.com/v1/webhooks

### Parameters
#### Request Body
- **data** (object) - Required - The webhook object.
  - **type** (string) - Required - Must be "webhooks".
  - **attributes** (object) - Required - Attributes of the webhook.
    - **url** (string) - Required - The URL endpoint to send webhook data to.
    - **events** (array of strings) - Required - A list of events to subscribe to (e.g., "order_created", "subscription_created").
    - **secret** (string) - Required - A signing secret for verifying webhook authenticity.
  - **relationships** (object) - Required - Relationships for the webhook.
    - **store** (object) - Required - The store the webhook belongs to.
      - **data** (object) - Required.
        - **type** (string) - Required - Must be "stores".
        - **id** (string) - Required - The ID of the store.

### Request Example
```json
{
  "data": {
    "type": "webhooks",
    "attributes": {
      "url": "https://example.com/webhooks/",
      "events": [
        "order_created",
        "subscription_created",
        "subscription_updated",
        "subscription_expired"
      ],
      "secret": "SIGNING_SECRET"
    },
    "relationships": {
      "store": {
        "data": {
          "type": "stores",
          "id": "1"
        }
      }
    }
  }
}
```

### Response
#### Success Response (200 or 201)
Details of the created webhook (structure not provided in source).
```

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

### Subscription Object with Customer Portal URL

Source: https://docs.lemonsqueezy.com/guides/developer-guide/customer-portal

A subscription object contains a signed customer_portal URL in the urls object. This URL is valid for 24 hours and automatically logs customers in.

```json
{
  ...
  "cancelled": false,
  "trial_ends_at": null,
  "billing_anchor": 30,
  "urls": {
    "update_payment_method": "https://my-store.lemonsqueezy.com/subscription/1/payment-details?expires=1688469629&signature=4577154142b49da48f73809288ef0f52ae6a91c860b7bdc22ff5bddba842a455",
    "customer_portal": "https://my-store.lemonsqueezy.com/billing?expires=1688469629&user=60000&signature=f040cb5a25ccebd8d05c2937e9a0559a750f5d5b8b32a40162ca43e130187d2c"
  },
  "renews_at": "2023-07-30T11:48:33.000000Z",
  "ends_at": null,
  ...
}

```

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

### Customize Checkout Overlay Appearance via URL

Source: https://docs.lemonsqueezy.com/guides/developer-guide/taking-payments

Customize the checkout overlay by setting query parameters like `embed`, `logo`, and `button_color`. Remember to URL-encode special characters like '#'.

```url
https://[STORE].lemonsqueezy.com/checkout/buy/[VARIANT_ID]
?embed=1
&logo=0&
button_color=%23111111
```

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

### Customize Receipt Emails via API

Source: https://docs.lemonsqueezy.com/guides/developer-guide/taking-payments

Configure receipt email text, links, and thank you notes when creating checkouts using the API. This allows for a branded and informative post-purchase experience.

```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": {
      "product_options": {
        "receipt_button_text": "Go to your account",
        "receipt_link_url": "https://example.com/dashboard/",
        "receipt_thank_you_note": "Thank you for signing up! Click on the button to access your account."
      }
    },
    "relationships": {
      ...
    }
  }
}'
```

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

### API Authentication Header

Source: https://docs.lemonsqueezy.com/guides/developer-guide/getting-started

Use this header to authenticate your API requests with your generated API key. Replace {api_key} with your actual key.

```http
Authorization: Bearer {api_key}

```

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

### Unsigned Customer Portal URL

Source: https://docs.lemonsqueezy.com/guides/developer-guide/customer-portal

This is the basic unsigned URL for the Customer Portal. Customers may need to log in if not already authenticated.

```text
https://[STORE].lemonsqueezy.com/billing

```

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

### Change Subscription Plan

Source: https://docs.lemonsqueezy.com/guides/developer-guide/managing-subscriptions

Use this PATCH request to change a subscription to a new product variant. Include the new variant ID in the request body.

```bash
curl -X "PATCH" "https://api.lemonsqueezy.com/v1/subscriptions/{subscription_id}" \
     -H 'Accept: application/vnd.api+json' \
     -H 'Content-Type: application/vnd.api+json' \
     -H 'Authorization: Bearer {api_key}' \
     -d '{
  "data": {
    "type": "subscriptions",
    "id": "{subscription_id}",
    "attributes": {
      "variant_id": {variant_id}
    }
  }
}'
```

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

### Add Lemon.js Script

Source: https://docs.lemonsqueezy.com/guides/developer-guide/lemonjs

Embed the Lemon.js library via CDN into the head or body of your HTML page to enable its functionality.

```html
<script src="https://app.lemonsqueezy.com/js/lemon.js" defer></script>

```

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

### Pre-fill Checkout Fields via API

Source: https://docs.lemonsqueezy.com/guides/developer-guide/taking-payments

When creating a checkout via the API, pass customer information within the `checkout_data` object.

```json
{
  "data": {
    "type": "checkouts",
    "attributes": {
      "checkout_data": {
        "email": "johndoe@example.com",
        "name": "John Doe"
      }
    },
    "relationships": {
      ...
    }
  }
}
```

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

### Create Expiring Checkout URL

Source: https://docs.lemonsqueezy.com/guides/developer-guide/taking-payments

Set an expiration date for a checkout URL by using the `expires_at` attribute. Checkouts will be invalidated after the specified date and time, preventing further purchases.

```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": { \
      "expires_at": "2023-04-30T23:59:59.000000Z" \
    }, \
    "relationships": { \
      ... \
    } \
  } \
}'
```

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

### Resume a Subscription

Source: https://docs.lemonsqueezy.com/guides/developer-guide/managing-subscriptions

Use this endpoint to resume a subscription that is in a grace period. This will change the status back to 'active' and continue the original payment schedule.

```curl
curl -X "PATCH" "https://api.lemonsqueezy.com/v1/subscriptions/{subscription_id}" \
     -H 'Accept: application/vnd.api+json' \
     -H 'Content-Type: application/vnd.api+json' \
     -H 'Authorization: Bearer {api_key}' \
     -d '{
  "data": {
    "type": "subscriptions",
    "id": "{subscription_id}",
    "attributes": {
      "cancelled": false
    }
  }
}'
```

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

### Pass Custom Data via URL Parameters

Source: https://docs.lemonsqueezy.com/guides/developer-guide/taking-payments

Include custom data in the checkout URL using query string parameters under the `checkout[custom]` key. This data is not visible to the customer.

```url
https://[STORE].lemonsqueezy.com/checkout/buy/[VARIANT_ID]?checkout[custom][user_id]=123
```

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

### Subscription URLs for Updating Payment Method

Source: https://docs.lemonsqueezy.com/guides/developer-guide/managing-subscriptions

This JSON snippet shows the structure of subscription data, including URLs for updating payment methods and accessing the customer portal. These URLs are time-sensitive.

```json
{
  "type": "subscriptions",
  "id": "1",
  "attributes": {
    ...
    "urls": {
      "update_payment_method": "https://my-store.lemonsqueezy.com/subscription/1/payment-details?expires=1674045831&signature=31cf3c83983a03a6cf92e4ec3b469fc044eace0a13183dcb1d7bc0da3bad6f31",
      "customer_portal": "https://my-store.lemonsqueezy.com/billing?expires=1674045831&signature=82ae290ceac8edd4190c82825dd73a8743346d894a8ddbc4898b97eb96d105a5"
    }
    ...
  }
}
```

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

### Set Custom Price for Checkout

Source: https://docs.lemonsqueezy.com/guides/developer-guide/taking-payments

Use the `custom_price` attribute to override the product's standard price for a specific checkout. This price excludes tax. The value must be in the currency's smallest unit.

```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": { \
      "custom_price": 599 \
    }, \
    "relationships": { \
      ... \
    } \
  } \
}'
```

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

### Create Checkout with Variant Quantities via API

Source: https://docs.lemonsqueezy.com/guides/developer-guide/usage-based-billing

When creating checkouts via the API, specify variant quantities within the 'checkout_data.variant_quantities' object.

```json
{
  "data": {
    "type": "checkouts",
    "attributes": {
      "checkout_data": {
        "variant_quantities": [
          {
            "variant_id": 1,
            "quantity": 10
          }
        ]
      }
    },
    "relationships": {
      "store": {
        "data": {
          "type": "stores",
          "id": "1"
        }
      },
      "variant": {
        "data": {
          "type": "variants",
          "id": "1"
        }
      }
    }
  }
}
```

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

### Query Subscription Item Response

Source: https://docs.lemonsqueezy.com/guides/developer-guide/usage-based-billing

The response from querying a subscription item includes details such as quantity, price ID, and usage-based billing status.

```json
{
  "type": "subscription-items",
  "id": "1",
  "attributes": {
    "subscription_id": 1,
    "price_id": 1,
    "quantity": 1,
    "is_usage_based": false,
    "created_at": "2023-07-18T12:16:24.000000Z",
    "updated_at": "2023-07-18T12:16:24.000000Z"
  },
  ...
}
```

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

### Change Subscription Billing Date

Source: https://docs.lemonsqueezy.com/guides/developer-guide/managing-subscriptions

Send a PATCH request to update a subscription's billing anchor. This allows you to set a specific day of the month for recurring charges. A proration will occur to adjust for the change in the billing period.

```bash
curl -X "PATCH" "https://api.lemonsqueezy.com/v1/subscriptions/{subscription_id}" \
     -H 'Accept: application/vnd.api+json' \
     -H 'Content-Type: application/vnd.api+json' \
     -H 'Authorization: Bearer {api_key}' \
     -d '{
  "data": {
    "type": "subscriptions",
    "id": "{subscription_id}",
    "attributes": {
      "billing_anchor": 1
    }
  }
}'
```

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

### Report Usage Increment via API

Source: https://docs.lemonsqueezy.com/guides/developer-guide/usage-based-billing

Use the 'increment' action to add a quantity to the existing usage for a subscription item, suitable for 'Sum of usage during period' aggregation.

```json
{
  "data": {
    "type": "usage-records",
    "attributes": {
      "quantity": 1,
      "action": "increment"
    },
    "relationships": {
      "subscription-item": {
        "data": {
          "type": "subscription-items",
          "id": "1"
        }
      }
    }
  }
}
```

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

### Resuming a subscription in grace period

Source: https://docs.lemonsqueezy.com/guides/developer-guide/managing-subscriptions

Resumes a subscription that is in a grace period, changing its status back to 'active' and continuing the original payment schedule.

```APIDOC
## PATCH /v1/subscriptions/{subscription_id}

### Description
Resumes a subscription that is in a grace period, changing its status back to `active` and continuing the original payment schedule.

### Method
PATCH

### Endpoint
/v1/subscriptions/{subscription_id}

### Parameters
#### Path Parameters
- **subscription_id** (integer) - Required - The ID of the subscription to resume.

#### Request Body
- **data** (object) - Required - The subscription object.
  - **type** (string) - Required - Must be "subscriptions".
  - **id** (string) - Required - The ID of the subscription.
  - **attributes** (object) - Required - Attributes to update.
    - **cancelled** (boolean) - Required - Set to `false` to resume the subscription.

### Request Example
```json
{
  "data": {
    "type": "subscriptions",
    "id": "{subscription_id}",
    "attributes": {
      "cancelled": false
    }
  }
}
```

### Response
#### Success Response (200)
- The updated subscription object.

#### Response Example
(Response structure not provided in source)
```

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

### Set Redirect URL for API Checkout

Source: https://docs.lemonsqueezy.com/guides/developer-guide/taking-payments

Customize the redirect URL for customers after a successful payment when creating checkouts via the API. This changes the button's destination in the confirmation modal.

```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": { \
      "product_options": { \
        "redirect_url": "https://example.com/dashboard" \
      } \
    }, \
    "relationships": { \
      ... \
    } \
  } \
}'
```

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

### Manually Unpause a Subscription

Source: https://docs.lemonsqueezy.com/guides/developer-guide/managing-subscriptions

Manually unpause a subscription by sending a PATCH request with the 'pause' attribute set to null. This will resume payment collection on the original schedule.

```curl
curl -X "PATCH" "https://api.lemonsqueezy.com/v1/subscriptions/{subscription_id}" \
     -H 'Accept: application/vnd.api+json' \
     -H 'Content-Type: application/vnd.api+json' \
     -H 'Authorization: Bearer {api_key}' \
     -d '{
  "data": {
    "type": "subscriptions",
    "id": "{subscription_id}",
    "attributes": {
      "pause": null
    }
  }
}'
```

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

### API Request Headers

Source: https://docs.lemonsqueezy.com/guides/developer-guide/getting-started

These headers are required for all requests to the Lemon Squeezy API, ensuring proper formatting and content type.

```http
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json

```

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

### Pass Custom Data via API

Source: https://docs.lemonsqueezy.com/guides/developer-guide/taking-payments

When creating a checkout via the API, use the `custom` object within `checkout_data` to pass arbitrary data. This data is returned in webhook events.

```json
{
  "data": {
    "type": "checkouts",
    "attributes": {
      "checkout_data": {
        "custom": {
          "user_id": 123
        }
      }
    },
    "relationships": {
      ...
    }
  }
}
```

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

### Report Usage Record

Source: https://docs.lemonsqueezy.com/guides/developer-guide/usage-based-billing

Reports usage for a subscription item, allowing for incrementing or setting the quantity based on the product's aggregation setting.

```APIDOC
## POST /v1/usage-records

### Description
Records customer usage for a subscription item, which can be used for usage-based billing.

### Method
POST

### Endpoint
https://api.lemonsqueezy.com/v1/usage-records

### Parameters
#### Request Body
- **data** (object) - Required - The usage record data.
  - **type** (string) - Required - Must be "usage-records".
  - **attributes** (object) - Required - Attributes for the usage record.
    - **quantity** (integer) - Required - The quantity of usage to record.
    - **action** (string) - Required - The action to perform. Use "increment" for sum aggregation, "set" for most recent aggregation.
  - **relationships** (object) - Required - Relationships for the usage record.
    - **subscription-item** (object) - Required - The subscription item relationship.
      - **data** (object) - Required - Data for the subscription item relationship.
        - **type** (string) - Required - Must be "subscription-items".
        - **id** (string) - Required - The ID of the subscription item.

### Request Example
```json
{
  "data": {
    "type": "usage-records",
    "attributes": {
      "quantity": 1,
      "action": "increment"
    },
    "relationships": {
      "subscription-item": {
        "data": {
          "type": "subscription-items",
          "id": "1"
        }
      }
    }
  }
}
```
```

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

### Event Data Structure

Source: https://docs.lemonsqueezy.com/guides/developer-guide/lemonjs

The object passed to the event handler contains an 'event' property. For 'Checkout.Success', it also includes 'data' with order details.

```javascript
{
  event: "PaymentMethodUpdate.Closed"
}

```

```javascript
{
  event: "Checkout.Success",
  data: {
    "store_id": 1,
    "customer_id": 1,
    "identifier": "104e18a2-d755-4d4b-80c4-a6c1dcbe1c10",
    "order_number": 1,
    ...
  }
}

```

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

### Pausing a subscription

Source: https://docs.lemonsqueezy.com/guides/developer-guide/managing-subscriptions

Pauses a subscription, temporarily stopping payment collection. This can be set to 'free' or 'void' mode and can optionally include a future unpause date.

```APIDOC
## PATCH /v1/subscriptions/{subscription_id}

### Description
Pauses a subscription, temporarily stopping payment collection. This can be set to 'free' or 'void' mode and can optionally include a future unpause date.

### Method
PATCH

### Endpoint
/v1/subscriptions/{subscription_id}

### Parameters
#### Path Parameters
- **subscription_id** (integer) - Required - The ID of the subscription to pause.

#### Request Body
- **data** (object) - Required - The subscription object.
  - **type** (string) - Required - Must be "subscriptions".
  - **id** (string) - Required - The ID of the subscription.
  - **attributes** (object) - Required - Attributes to update.
    - **pause** (object) - Required - Object to configure the pause.
      - **mode** (string) - Required - The mode of the pause. Can be `free` or `void`.
      - **resumes_at** (string) - Optional - The date and time when the subscription should automatically unpause. Format: ISO 8601.

### Request Example
```json
{
  "data": {
    "type": "subscriptions",
    "id": "{subscription_id}",
    "attributes": {
      "pause": {
        "mode": "free",
        "resumes_at": "2023-06-30T00:00:00.000000Z"
      }
    }
  }
}
```

### Response
#### Success Response (200)
- The updated subscription object with pause details.

#### Response Example
(Response structure not provided in source)
```

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

### Manually unpausing a paused subscription

Source: https://docs.lemonsqueezy.com/guides/developer-guide/managing-subscriptions

Manually unpauses a subscription that was previously paused, resuming payment collection on its original schedule.

```APIDOC
## PATCH /v1/subscriptions/{subscription_id}

### Description
Manually unpauses a subscription that was previously paused, resuming payment collection on its original schedule.

### Method
PATCH

### Endpoint
/v1/subscriptions/{subscription_id}

### Parameters
#### Path Parameters
- **subscription_id** (integer) - Required - The ID of the subscription to unpause.

#### Request Body
- **data** (object) - Required - The subscription object.
  - **type** (string) - Required - Must be "subscriptions".
  - **id** (string) - Required - The ID of the subscription.
  - **attributes** (object) - Required - Attributes to update.
    - **pause** (null) - Required - Set to `null` to unpause the subscription.

### Request Example
```json
{
  "data": {
    "type": "subscriptions",
    "id": "{subscription_id}",
    "attributes": {
      "pause": null
    }
  }
}
```

### Response
#### Success Response (200)
- The updated subscription object, now active and resuming payments.

#### Response Example
(Response structure not provided in source)
```

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

### Disable Proration When Changing Plans

Source: https://docs.lemonsqueezy.com/guides/developer-guide/managing-subscriptions

When changing a subscription plan, you can disable proration by setting `"disable_prorations": true` in the request body. This prevents immediate charges or credits for the plan difference.

```bash
curl -X "PATCH" "https://api.lemonsqueezy.com/v1/subscriptions/{subscription_id}" \
     -H 'Accept: application/vnd.api+json' \
     -H 'Content-Type: application/vnd.api+json' \
     -H 'Authorization: Bearer {api_key}' \
     -d '{
  "data": {
    "type": "subscriptions",
    "id": "{subscription_id}",
    "attributes": {
      "variant_id": {variant_id},
      "disable_prorations": true
    }
  }
}'
```

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

### Pause a Subscription

Source: https://docs.lemonsqueezy.com/guides/developer-guide/managing-subscriptions

Pause a subscription to temporarily stop payment collection. You can set the mode to 'free' or 'void' and optionally specify a date for automatic unpausing.

```curl
curl -X "PATCH" "https://api.lemonsqueezy.com/v1/subscriptions/{subscription_id}" \
     -H 'Accept: application/vnd.api+json' \
     -H 'Content-Type: application/vnd.api+json' \
     -H 'Authorization: Bearer {api_key}' \
     -d '{
  "data": {
    "type": "subscriptions",
    "id": "{subscription_id}",
    "attributes": {
      "pause": {
        "mode": "free",
        "resumes_at": "2023-06-30T00:00:00.000000Z"
      }
    }
  }
}'
```

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

### Update Subscription Item Quantity via API

Source: https://docs.lemonsqueezy.com/guides/developer-guide/usage-based-billing

Modify the 'quantity' attribute of a subscription item to change the number of units charged on the next renewal. A prorated amount is added for quantity increases.

```json
{
  "data": {
    "type": "subscription-items",
    "id": "1",
    "attributes": {
      "quantity": 5
    }
  }
}
```
Tokens:
Raw