API Reference

The Lemon Squeezy API is a REST API that has predictable resource-oriented URLs, returns valid JSON:API encoded responses and uses standard HTTP response codes, authentication, and verbs.

Currently, the API is considered BETA and as such only provides read-only endpoints for most resources. In time we plan to expand that API and add CRUD endpoints for all resources.


Making Requests

All API requests must be made over HTTPS to https://api.lemonsqueezy.com. Calls made over plain HTTP will fail. API requests without authentication will also fail.

The Lemon Squeezy API is compatible with the JSON:API spec. As per the spec, the following headers must be included with all requests to the API:

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

If you're attempting to make a request with a null Origin header (e.g. from a sandboxed iframe in a Figma plugin) then you can use the https://api-cors-anywhere.lemonsqueezy.com API proxy URL instead.


Authentication

The Lemon Squeezy API uses API keys to authenticate requests. You can view and manage your API keys in your account settings.

Note that API keys are live and test mode specific. A test mode API key will only return test mode data and vice versa.

Be sure to keep your API keys secure! Do not share your API keys in publicly accessible areas such as GitHub, client-side code, and so forth.

To authenticate requests, API keys must be included in the Authorization header as a Bearer token in the format:

Authorization: Bearer {api_key}

Unauthenticated requests will receive a 401 Unauthorized response.


Rate Limiting

To make it easier to determine if your application is being rate-limited, or is approaching that level, we add the following HTTP headers on our successful responses:

  • X-Ratelimit-Limit
  • X-Ratelimit-Remaining

There is a limit of 300 API calls per minute.

If you exceed the limit you will receive a 429 Too Many Requests response.


Errors

The Lemon Squeezy API uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, an action failed, etc). Codes in the 5xx range indicate an error with our servers (these are rare).

A 4xx error will always contain valid JSON:API errors array in the response. Each error object will usually contain several fields that explain the error, including status, title, detail etc.

Some common error responses are listed below:

  • 400 Bad Request - Your request may be malformed
  • 401 Unauthorized - Your API key is wrong, or your user does not have access to this resource
  • 403 Forbidden - The record requested is hidden
  • 404 Not Found - The specified record could not be found
  • 405 Method Not Allowed - You tried to access a record with an invalid method
  • 422 Unprocessable Entity - The requested method cannot process for the record in question
  • 429 Too Many Requests - You have exceeded the API rate limit

Pagination

The Lemon Squeezy API uses page-based pagination for all “list” endpoints. The responses will contain valid JSON:API pagination objects in the response. This includes a top-level link object with first, last, prev, next links as well as a pagination object in meta.page.

Request

The page query parameter is reserved for pagination and can be used like this:

GET /v1/orders?page[number]=3&page[size]=100

Here, page[number] is the index of the page you want to retrieve and page[size] is the number of results you want to return in the response. By default, the page[size] is 10 and is capped at 100.


To help cut down on multiple requests, the Lemon Squeezy API supports the JSON:API spec for including related resources. Related resources can be included in the same response by using the include query parameter.

Request

For example, the following request will include all Variants that belong to the Product with the ID 100:

GET /v1/products/100?include=variants

The response will contain a new top-level included array which will contain the related resources.

Note that you can still fetch related resources separately using nested retrieve requests:

GET /v1/products/100/variants

Versioning

The Lemon Squeezy API includes the major version number as a prefix for all endpoints (e.g. /v1). While we reserve the right to make changes to the API as we see fit, we endeavour not to make any changes to the API that will break backwards compatibility.

In the rare case that we do need to break backwards compatibility, we will release a new major version of the API and deprecate the old version. This will give any integrations time to migrate to the new version.

Lemon Squeezy considers the following changes to be backwards-compatible:

  • Adding new API resources.
  • Adding new optional request parameters to existing API methods.
  • Adding new properties to existing API responses.
  • Changing the order of properties in existing API responses.
  • Adding new webhook event types.

Resource Object Structure

All API responses follow the document structure outlined in the JSON:API spec. This means every response will contain a top-level data object/array which will contain one/many resource objects. Each resource object will contain the following properties:

  • type - The type of the resource (e.g. products, orders, etc.)
  • id - The id of the resource
  • attributes - An object representing the resources data

A resource object may also contain optional properties such as relationships, links and meta.


Example App

If you're looking for some inspiration or guidance on how you might use our API, check out our example app created using Vue.js that demonstrates how you might use the API in your own apps.