A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The Lemon Squeezy API is how an app or AI agent works with a store: reading orders and products, creating a hosted checkout, managing a customer's subscription, and issuing license keys for software. Access is granted through an API key sent as a bearer token, and the key carries full account access because Lemon Squeezy keys have no per-resource scopes. A state change emits an event that Lemon Squeezy can deliver to a registered endpoint, signed so the receiver can confirm it.
How an app or AI agent connects to Lemon Squeezy determines what it can reach. There is a route for making calls, authenticated by an API key, and a route for receiving events, where Lemon Squeezy posts signed notifications to a registered endpoint.
The store API is a JSON:API REST interface at https://api.lemonsqueezy.com/v1. Requests and responses use the application/vnd.api+json media type, set on both Accept and Content-Type. A call authenticates with an API key sent as a bearer token, lists are page-based, related records come in via the include parameter, and filters use filter[field]=value.
Lemon Squeezy POSTs a JSON payload to a registered HTTPS endpoint when a subscribed event fires, like order_created or subscription_updated. Each request carries an X-Signature header, an HMAC-SHA256 hash of the raw body computed with the webhook's signing secret, which the receiver recomputes and compares to confirm the request came from Lemon Squeezy. Webhooks are managed in the dashboard or through the webhooks API.
A single API key, created in account settings, authenticates every store-API call as a bearer token in the Authorization header. The key is account-level with no granular scopes, so it can read and write across every resource the account owns. Each key belongs to one mode, test or live, which is the only native access boundary. A key is shown once at creation and should never be exposed in client code.
The Lemon Squeezy API is split into areas an agent can act on, like stores, products, orders, subscriptions, customers, discounts, and license keys. Most methods read store data, and a smaller set writes, like creating a checkout, updating a subscription, or disabling a license key.
Methods for reading store configuration.
Methods for reading the product catalog, its variants, and prices.
Methods for reading orders and their line items.
Methods for reading and changing subscriptions and their invoices.
Methods for reading and managing customer records.
Methods for reading and creating hosted checkout sessions.
Methods for reading, creating, and removing discount codes.
Methods for reading and updating software license keys.
Methods for managing the event subscriptions an integration listens on.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
StoresMethods for reading store configuration.2 | ||||||
| GET | /v1/stores | List all stores on the account. | read | — | Current | |
Read-only. Lemon Squeezy API keys have no per-resource scopes, so any valid key can call this. Acts onstore Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v1/stores/:id | Retrieve a single store by id. | read | — | Current | |
Read-only. No per-endpoint scope exists on a Lemon Squeezy key. Acts onstore Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Products & VariantsMethods for reading the product catalog, its variants, and prices.5 | ||||||
| GET | /v1/products | List all products in the catalog. | read | — | Current | |
Read-only. No per-endpoint scope exists on a Lemon Squeezy key. Acts onproduct Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v1/products/:id | Retrieve a single product by id. | read | — | Current | |
Read-only. No per-endpoint scope exists on a Lemon Squeezy key. Acts onproduct Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v1/variants | List all product variants. A variant holds a product's pricing and options. | read | — | Current | |
Read-only. Often called to sync the catalog after products change. Acts onvariant Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v1/variants/:id | Retrieve a single product variant by id. | read | — | Current | |
Read-only. No per-endpoint scope exists on a Lemon Squeezy key. Acts onvariant Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v1/prices | List all prices defined for variants. | read | — | Current | |
Read-only. No per-endpoint scope exists on a Lemon Squeezy key. Acts onprice Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
OrdersMethods for reading orders and their line items.4 | ||||||
| GET | /v1/orders | List all orders, filterable by store, customer, or email. | read | — | Current | |
Read-only. Exposes sales records and customer purchase data. Acts onorder Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v1/orders/:id | Retrieve a single order by id. | read | — | Current | |
Read-only. No per-endpoint scope exists on a Lemon Squeezy key. Acts onorder Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v1/order-items | List all order items, the individual line items that make up orders. | read | — | Current | |
Read-only. No per-endpoint scope exists on a Lemon Squeezy key. Acts onorder-item Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v1/order-items/:id | Retrieve a single order item by id. | read | — | Current | |
Read-only. No per-endpoint scope exists on a Lemon Squeezy key. Acts onorder-item Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
SubscriptionsMethods for reading and changing subscriptions and their invoices.6 | ||||||
| GET | /v1/subscriptions | List all subscriptions, filterable by store, order, product, or status. | read | — | Current | |
Read-only. No per-endpoint scope exists on a Lemon Squeezy key. Acts onsubscription Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v1/subscriptions/:id | Retrieve a single subscription by id. | read | — | Current | |
Read-only. No per-endpoint scope exists on a Lemon Squeezy key. Acts onsubscription Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /v1/subscriptions/:id | Update a subscription: change the plan or variant, pause or resume it, or adjust the billing date. | write | — | Current | |
Changes a customer's billing. No granular scope; any valid key can call this. Acts onsubscription Permission (capability)None required VersionAvailable since the API’s base version Webhook event subscription_updatedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /v1/subscriptions/:id | Cancel a subscription; it stays active until the end of the current billing period. | write | — | Current | |
Ends recurring billing. No granular scope; any valid key can call this. Acts onsubscription Permission (capability)None required VersionAvailable since the API’s base version Webhook event subscription_cancelledRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v1/subscription-invoices | List all subscription invoices, the billing records for subscription renewals. | read | — | Current | |
Read-only. No per-endpoint scope exists on a Lemon Squeezy key. Acts onsubscription-invoice Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v1/subscription-invoices/:id | Retrieve a single subscription invoice by id. | read | — | Current | |
Read-only. No per-endpoint scope exists on a Lemon Squeezy key. Acts onsubscription-invoice Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
CustomersMethods for reading and managing customer records.4 | ||||||
| GET | /v1/customers | List all customers, filterable by store or email. | read | — | Current | |
Read-only. Exposes customer names, emails, and revenue. Acts oncustomer Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v1/customers/:id | Retrieve a single customer by id. | read | — | Current | |
Read-only. No per-endpoint scope exists on a Lemon Squeezy key. Acts oncustomer Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v1/customers | Create a customer record, with a name and email, tied to a store. | write | — | Current | |
Requires a store relationship. No granular scope; any valid key can call this. Acts oncustomer Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /v1/customers/:id | Update a customer's details, or set status to archived so they stop receiving marketing email. | write | — | Current | |
Changes real customer data. No granular scope; any valid key can call this. Acts oncustomer Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
CheckoutsMethods for reading and creating hosted checkout sessions.3 | ||||||
| GET | /v1/checkouts | List all custom checkouts created via the API. | read | — | Current | |
Read-only. No per-endpoint scope exists on a Lemon Squeezy key. Acts oncheckout Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v1/checkouts/:id | Retrieve a single checkout by id. | read | — | Current | |
Read-only. No per-endpoint scope exists on a Lemon Squeezy key. Acts oncheckout Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v1/checkouts | Create a custom hosted checkout for a variant, with optional prefilled data and discounts. A preview option returns the totals with discounts and tax applied. | write | — | Current | |
Returns a payable checkout URL. No granular scope; any valid key can call this. Acts oncheckout Permission (capability)None required VersionAvailable since the API’s base version Webhook event order_createdRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
DiscountsMethods for reading, creating, and removing discount codes.3 | ||||||
| GET | /v1/discounts | List all discount codes. | read | — | Current | |
Read-only. No per-endpoint scope exists on a Lemon Squeezy key. Acts ondiscount Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v1/discounts | Create a discount code, fixed or percentage, scoped to a store and optional products. | write | — | Current | |
Changes what customers can be charged. No granular scope; any valid key can call this. Acts ondiscount Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /v1/discounts/:id | Delete a discount code by id. | write | — | Current | |
Irreversible. No granular scope; any valid key can call this. Acts ondiscount Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
License keysMethods for reading and updating software license keys.3 | ||||||
| GET | /v1/license-keys | List all software license keys issued by the store. | read | — | Current | |
Read-only. No per-endpoint scope exists on a Lemon Squeezy key. Acts onlicense-key Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v1/license-keys/:id | Retrieve a single license key by id. | read | — | Current | |
Read-only. No per-endpoint scope exists on a Lemon Squeezy key. Acts onlicense-key Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /v1/license-keys/:id | Update a license key: change its activation limit or expiry, or disable it. | write | — | Current | |
Setting disabled to true revokes a customer's software license. No granular scope; any valid key can call this. Acts onlicense-key Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
WebhooksMethods for managing the event subscriptions an integration listens on.5 | ||||||
| GET | /v1/webhooks | List all webhooks registered for the store. | read | — | Current | |
Read-only. No per-endpoint scope exists on a Lemon Squeezy key. Acts onwebhook Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v1/webhooks | Create a webhook with a URL, a list of events, and a signing secret. | write | — | Current | |
Sets where store events are sent. No granular scope; any valid key can call this. Acts onwebhook Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v1/webhooks/:id | Retrieve a single webhook by id. | read | — | Current | |
Read-only. No per-endpoint scope exists on a Lemon Squeezy key. Acts onwebhook Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /v1/webhooks/:id | Update a webhook's URL, events, or signing secret. | write | — | Current | |
Changes where store events are sent. No granular scope; any valid key can call this. Acts onwebhook Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /v1/webhooks/:id | Delete a webhook by id so it stops receiving events. | write | — | Current | |
Stops event delivery. No granular scope; any valid key can call this. Acts onwebhook Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Lemon Squeezy can notify an app when something happens in a store, like an order being placed or a subscription changing. It posts a JSON payload describing the event with a signature header, so an integration learns about activity without polling.
| Event | What it signals | Triggered by |
|---|---|---|
order_created | A new order was placed in the store. An integration uses this to record the sale and fulfill the purchase. | /v1/checkouts |
order_refunded | An order was refunded, fully or partially. An integration reverses access or entitlements granted by the order. | In-app only |
subscription_created | A new subscription was created for a customer. | /v1/checkouts |
subscription_updated | A subscription changed, like a plan switch, a pause or resume, a status change, or a renewal date moving. | /v1/subscriptions/:id |
subscription_cancelled | A subscription was cancelled and will end at the close of the current billing period. | /v1/subscriptions/:id/v1/subscriptions/:id |
subscription_expired | A subscription has ended and the customer no longer has access. | In-app only |
subscription_payment_success | A subscription invoice was paid successfully. An integration saves billing history on this event. | In-app only |
license_key_created | A license key was created for a purchase of a license-enabled product. | In-app only |
Lemon Squeezy limits how fast an app can call the store API, measured as requests per minute against the API key, with a separate, lower limit on the license-key validation API.
The store API allows 300 requests per minute against an API key. The separate license-key validation API, used to activate and validate license keys in deployed software, is limited to 60 requests per minute. Going over returns HTTP 429, so a client should pace calls and back off on a 429 before retrying.
List endpoints are page-based following JSON:API: page[size] sets how many records a page returns (default 10, range 1 to 100) and page[number] selects the page. The response carries a meta.page object with the current page, page size, total record count (meta.page.total), and last page number (meta.page.lastPage), plus JSON:API links for first, last, next, and prev.
A list page returns at most 100 records, the maximum value of page[size]. The include parameter pulls related resources into the same response to cut round-trips, and filter[field]=value narrows a list. Requests and responses use the application/vnd.api+json media type.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 400 | bad_request | The request was malformed, for example a JSON:API body that does not follow the expected structure or the wrong media type. | Set Accept and Content-Type to application/vnd.api+json, fix the request body to the JSON:API shape, and resend. |
| 401 | Unauthenticated | No valid API key was provided. The error detail reads 'Unauthenticated.' with title 'Unauthorized'. | Send a valid API key as a bearer token in the Authorization header, and confirm it is for the right mode (test or live). |
| 404 | Not Found | The requested resource does not exist, or is not visible to this key or mode. | Check the resource id, and confirm the key and mode match where the resource lives. |
| 422 | Unprocessable Entity | The request was well-formed but contained invalid data, for example a missing required relationship like a store or variant id. The errors array names the offending field. | Read the detail and source pointer in each errors entry, correct the field, and resend. |
| 429 | Too Many Requests | The request rate exceeded the limit (300 per minute on the store API, 60 per minute on the license validation API). | Pace requests under the limit and retry after a short backoff. |
Lemon Squeezy carries one major version in the path and ships dated, backward-compatible additions through its API changelog rather than minting new version numbers.
The store API carries one major version in the path and ships backward-compatible additions through the API changelog rather than dated version strings. Recent additions include customer create and update, full webhook CRUD, affiliates, subscription items, prices, and refund endpoints.
Merchants can manually simulate individual order webhooks from the test-mode dashboard, and a new affiliate_activated webhook event was added.
Merchants can issue partial refunds, choosing exactly how much to refund on a given order.
The path version is stable; new resources and fields arrive additively.
Lemon Squeezy API changelog ↗Bollard AI sits between a team's AI agents and Lemon Squeezy. Grant each agent exactly the access it needs, read or write, resource by resource, and every call is checked and logged.