Lemon Squeezy Getting Started: Account, Keys, and First API Call (2026)

Getting started overview

Integrating with Lemon Squeezy involves a sequence of steps designed to enable the sale of digital products, management of subscriptions, and handling of global tax compliance through its platform. The initial setup focuses on obtaining necessary credentials and making a foundational API request to confirm connectivity and authentication. This guide outlines the process from account creation to a successful first API call, providing a practical pathway for developers to begin using Lemon Squeezy's e-commerce and payment features.

Lemon Squeezy provides a RESTful API, which follows standard HTTP methods and status codes, and supports JSON for request and response bodies. Authentication primarily uses API keys. Official SDKs are available for PHP, Ruby, Python, and JavaScript, which can abstract some of the direct HTTP request handling. For environments without a dedicated SDK, direct HTTP requests can be made using standard libraries or tools like cURL.

The core objective of this getting started guide is to establish a basic integration that allows for programmatic interaction with your Lemon Squeezy store. This includes creating and managing products, customers, and subscriptions, which are fundamental to utilizing the platform's capabilities. Understanding the authentication mechanism and the structure of API requests is crucial for building robust integrations.

Here's a quick reference table for the essential steps:

Create an account and get keys

To begin using Lemon Squeezy, you must first create an account. Navigate to the Lemon Squeezy website and complete the registration process. This typically involves providing an email address, setting a password, and agreeing to the terms of service.

After successfully signing up and logging into your dashboard, the next critical step is to generate an API key. API keys are essential for authenticating your requests to the Lemon Squeezy API, ensuring that only authorized applications can interact with your store data. Follow these steps to generate your API key:

1. Log in to your Lemon Squeezy dashboard.
2. Navigate to Settings in the left-hand menu.
3. Click on the API tab.
4. Locate the section for generating new API keys.
5. Click the "Create API Key" button. You may be prompted to give your key a descriptive name (e.g., "Development Integration").
6. Once generated, the API key will be displayed. It is crucial to copy this key immediately and store it securely, as it will only be shown once. If you lose it, you will need to generate a new key.

Lemon Squeezy's API keys function as bearer tokens for authentication. When making an API request, you will include your API key in the Authorization header, prefixed with Bearer. For example: Authorization: Bearer YOUR_API_KEY. This is a common practice for securing RESTful APIs, as detailed in RFC 6750 for Bearer Token Usage.

Before making your first API request, it's also advisable to create a test store and at least one product within your Lemon Squeezy dashboard. This provides data to retrieve and manipulate, confirming your API integration is working correctly. Go to the "Products" section in your dashboard and create a simple digital product for testing purposes, ensuring it is marked as "published".

Your first request

With your Lemon Squeezy account active, an API key generated, and a test product created, you are ready to make your first authenticated API request. This example demonstrates fetching a list of your products using cURL, a widely available command-line tool for making HTTP requests. This confirms that your API key is correctly configured and that you can communicate with the Lemon Squeezy API.

The Lemon Squeezy API documentation provides detailed endpoints, but a common starting point is the "List all products" endpoint. The base URL for the API is https://api.lemonsqueezy.com/v1/, and the specific endpoint for products is products.

Prerequisites:

• Your Lemon Squeezy API Key (e.g., sk_xxxxxxxxxxxxxxxxxxxx).
• A published product in your Lemon Squeezy store.
• cURL installed on your system. Most Unix-like systems and macOS include cURL by default. For Windows, you might need to install it or use an alternative like Postman.

Making the request with cURL:

Open your terminal or command prompt and execute the following command. Replace YOUR_API_KEY with the actual API key you generated from your Lemon Squeezy dashboard.

curl -X GET \
  'https://api.lemonsqueezy.com/v1/products' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Expected Response:

A successful response (HTTP status code 200 OK) will return a JSON object containing an array of product resources. If you have created a test product, you should see it listed in the data array. The response structure adheres to the JSON:API specification, which is a standard for building APIs that define how clients can request and modify resources. More information on this structure can be found in the JSON:API specification.

{
  "jsonapi": {
    "version": "1.0"
  },
  "links": {
    "first": "https://api.lemonsqueezy.com/v1/products?page%5Bnumber%5D=1&page%5Bsize%5D=10",
    "last": "https://api.lemonsqueezy.com/v1/products?page%5Bnumber%5D=1&page%5Bsize%5D=10"
  },
  "data": [
    {
      "type": "products",
      "id": "12345",
      "attributes": {
        "name": "My Test Product",
        "slug": "my-test-product",
        "description": "<p>This is a test product.</p>",
        "status": "published",
        "status_formatted": "Published",
        "thumb_url": "https://example.com/thumb.png",
        "large_thumb_url": "https://example.com/large_thumb.png",
        "price": 1999,
        "price_formatted": "$19.99",
        "buy_now_url": "https://app.lemonsqueezy.com/buy/12345",
        "created_at": "2023-01-01T12:00:00.000000Z",
        "updated_at": "2023-01-01T12:00:00.000000Z"
      },
      "relationships": {
        "store": {
          "links": {
            "related": "https://api.lemonsqueezy.com/v1/products/12345/store",
            "self": "https://api.lemonsqueezy.com/v1/products/12345/relationships/store"
          }
        },
        "variants": {
          "links": {
            "related": "https://api.lemonsqueezy.com/v1/products/12345/variants",
            "self": "https://api.lemonsqueezy.com/v1/products/12345/relationships/variants"
          }
        }
      },
      "links": {
        "self": "https://api.lemonsqueezy.com/v1/products/12345"
      }
    }
  ]
}

If you receive a similar JSON response with your product data, your initial integration is successful. You have successfully authenticated and retrieved data from the Lemon Squeezy API.

Common next steps

After successfully making your first API request, you can explore more advanced functionalities and integrate Lemon Squeezy deeper into your application. Here are some common next steps:

1. Explore other API Endpoints: Review the comprehensive Lemon Squeezy API reference to understand the full range of available endpoints. You can manage customers, subscriptions, orders, discounts, and more. For instance, you might want to create a customer programmatically or manage a subscription lifecycle.

2. Implement Webhooks: Webhooks are crucial for receiving real-time notifications about events in your Lemon Squeezy store, such as new orders, subscription updates, or product changes. This allows your application to react to events without constantly polling the API. Set up webhook endpoints in your application and configure them in your Lemon Squeezy dashboard under Settings > Webhooks. The Lemon Squeezy webhooks guide provides detailed instructions.

3. Utilize Official SDKs: While direct HTTP requests offer flexibility, using one of the official Lemon Squeezy SDKs for PHP, Ruby, Python, or JavaScript can streamline development. SDKs typically handle authentication, request formatting, and response parsing, reducing boilerplate code and potential errors.

4. Integrate Checkout: For selling products, you'll need to integrate Lemon Squeezy's checkout system. This can involve generating "buy now" URLs or embedding the checkout experience directly into your site using their JavaScript library. Refer to the Lemon Squeezy checkout documentation for implementation details.

5. Error Handling and Logging: Implement robust error handling in your integration to gracefully manage API errors, network issues, and unexpected responses. Log API requests and responses to aid in debugging and monitoring your integration's health.

6. Testing Environment: Before deploying to production, thoroughly test your integration in a development or staging environment. This includes testing various scenarios, such as successful purchases, failed payments, subscription renewals, and cancellations.

7. Security Best Practices: Always follow security best practices, such as protecting your API keys, validating webhook signatures, and sanitizing all user inputs. Lemon Squeezy provides guidance on API security practices.

Troubleshooting the first call

Encountering issues during your first API call is common. Here are some typical problems and their solutions:

1. "401 Unauthorized" or "Invalid API Key":

   • Cause: The most common reason is an incorrect or missing API key in the Authorization header.
   • Solution: Double-check that your API key is correct and that it's included in the Authorization: Bearer YOUR_API_KEY header. Ensure there are no leading/trailing spaces or typos. Remember that API keys are case-sensitive. Verify you are using a live API key for production requests and a test API key for sandbox environments, if applicable (Lemon Squeezy primarily uses a single API key for both, but some platforms distinguish).

2. "404 Not Found":

   • Cause: The endpoint URL is incorrect, or the resource you're trying to access does not exist.
   • Solution: Verify the API endpoint URL against the Lemon Squeezy API documentation. Ensure correct spelling and path segments. If fetching a specific resource (e.g., a product by ID), confirm the ID is valid and the resource exists in your store.

3. "422 Unprocessable Entity" or "Invalid Data":

   • Cause: This usually occurs with POST or PUT requests when the request body contains malformed JSON or invalid data according to the API's requirements.
   • Solution: Review the request body carefully. Ensure it's valid JSON and adheres to the structure and data types specified in the API documentation for the particular endpoint. Check for missing required fields or incorrect data formats.

4. Network Issues / Connection Refused:

   • Cause: Your local network, firewall, or an issue with the API server itself might be preventing the request from reaching Lemon Squeezy.
   • Solution: Check your internet connection. Temporarily disable any aggressive firewall rules. If the issue persists, check the Lemon Squeezy status page to see if there are any reported outages or maintenance.

5. Missing Accept or Content-Type Headers:

   • Cause: Lemon Squeezy's API, following JSON:API standards, expects specific Accept and Content-Type headers.
   • Solution: Ensure your requests include -H 'Accept: application/vnd.api+json' and -H 'Content-Type: application/vnd.api+json'.

6. Empty Response or Unexpected Data Structure:

   • Cause: While the request might technically succeed (e.g., 200 OK), the data returned might not be what you expect, possibly due to filtering, pagination, or an empty dataset.
   • Solution: If you're fetching products, ensure you have actually created and published products in your Lemon Squeezy dashboard. Review any query parameters you might be sending (e.g., for filtering or pagination) to ensure they are correct and not inadvertently limiting your results.

Always consult the Lemon Squeezy API documentation for the most accurate and up-to-date troubleshooting information and specific error codes.