Welcome to the LemonStand REST API documentation!


The LemonStand API uses an Authorization header to verify all requests. You must first create a new (or acquire an existing) API access token from your store administration area. After you have acquired your token you can use it to access other resources within the token scope.

  1. Log into the /backend of your store.
  2. Navigate to the API section under the Integrations menu tab.
  3. Add a new API key and do not share the secret or access token with anyone.

Making a Call

Once you have your access token you can then start to make calls to the API. Throughout our documentation you will see different URLs (or End-Points), that when called in different ways will return information, and in some cases perform a specific action.

HTTP Methods

We’ve tried to make the API as simple as possible and utilize HTTP methods to keep the range of end-points/URLs to a minimum. We’ve also made sure that a single call is enough to perform an action.

The methods you’ll see throughout are our API are:

Method Usage
HEAD Can be issued against any resource to get just the HTTP header info.
GET The most common method, used to retrieve data.
POST Used to create or insert objects.
PUT Used for replacing resources or collections.
PATCH Used for updating resources with partial data.
DELETE Used to delete or remove objects.
OPTIONS Used to return available HTTP methods and other options.

Making a Request

There are numerous ways to make requests to the API, throughout this guide we’ll focus on CURL as it is one of the most commonly used libraries available. If you are happier using something else to perform these actions that is not a problem and the API will work with any library capable of setting headers and making regular HTTP calls.

Along with every request you make, your access token will be required as a header, and will be set as a header like so:

Authorization: Bearer <api token>

The API endpoint to make calls on depends on your store name. An example API request may look like this:

$ curl https://<store> \
    -H "Authorization: Bearer <api token>" \

If you are sending data to the API, you need to make sure you correctly set the Content-Type header:

$ curl -X PATCH https://<store> \
    -H 'Authorization: Bearer <api token>' \
    -H 'Content-Type: application/json' \
    -d '{"in_stock_amount":400}'

Notice the URI of the API endpoint is https://<store></store>. If the store you signed up with LemonStand is, you would make API calls to <a href=""></a>.

Embedding Data

You can embed multiple resources into many of the endpoints to allow for more fine grained data manipulation. For example, if you need to get all orders, but also need the customer data as well as each customers address, you can used nested embedding. An example of this type of request would look like this:

$ curl https://<store>,customer.shippingAddresses \
    -H "Authorization: Bearer <api token>" \


There are three (3) parameters available to collections in order to make paginating result sets easier.

Parameter Usage
cursor This sets where to start returning IDs from. In SQL, an example would be select * from products where id > 50; where 50 is the cursor.
limit How many items to return in the collection. The default for all collections is 250.
page Which page in the set to return.


All data is sent and received as JSON. All requests sent to the API as JSON must have the following header attached.

Content-Type: application/json

Blank fields are included as null instead of being omitted. All timestamps are returned in ISO 8601 format.




Notice that the format includes a full timezone offset (-0700) and time/date are separated by T.

Client Errors

All error objects have message properties so that your client can tell what the problem is.

Sending invalid JSON will result in a 400 Bad Request response:

HTTP/1.1 400 Bad Request
Content-Length: 135</code>
  "meta": {
    "status": 422,
    "success": false
  "error": {
    "message": "Problem parsing JSON."

Sending invalid fields will result in a 422 Unprocessable Entity response:

HTTP/1.1 422 Unprocessable Entity
Content-Length: 249
  "meta": {
    "status": 422,
    "success": false
  "error": {
    "message": {
      "sku": [
        "The value is already in use"
      "url_name": [
        "The value is already in use"

Sending an invalid access token will result in a 401 Unauthorized response:

HTTP/1.1 401 Unauthorized
Content-Length: 123
  "meta": {
    "status": 401,
    "success": false
  "error": {
    "message": "Access token is not valid"


Data Summary
February 8, 2017
    Added custom field endpoints
October 2, 2015
    Added endpoints for orders
July 22, 2015
    Added endpoints for product reviews.
May 12, 2015
    Added product extras.
May 11, 2015
    Added product embed to order items. Added tax classes. Added tax class rates.
April 27, 2015
    Update/Create groups via the customer endpoint.
April 23, 2015
    Added shipping_method embed to shipments endpoint.
March 30, 2015
    Added endpoints for product variants.
March 21, 2015
    Added endpoint for webhooks. [Available on the Growth plan and higher.]
November 4, 2014
    Added endpoint for product types.
November 3, 2014
    Added support for customer groups. Added support (list only) for product variants. Added support for volume (tiered) pricing. [Available on the Professional plan and higher.]