API

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 all 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

Authentication

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

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.

Authentication

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

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.