Introduction

Welcome to the LemonStand REST API documentation! We’re working as fast as we can to give you complete coverage of all the features that are already available in LemonStand, as well as helpful guides and more SDK examples.

Getting Started

To help you get started with the API we’ve put together a few examples. Each of these are designed to get you up and running as fast as possible and ease the initial processes involved.

Authentication

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 y5QNsEEGg8s9XqiQFuqGOB5a1zV22pGRFJgHgCbH

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

$ curl https://<store>.lemonstand.com/api/v2/product/1 \
    -H "Authorization: Bearer y5QNsEEGg8s9XqiQFuqGOB5a1zV22pGRFJgHgCbH" \

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>.lemonstand.com/api/v2/product/1 \
    -H 'Authorization: Bearer y5QNsEEGg8s9XqiQFuqGOB5a1zV22pGRFJgHgCbH' \
    -H 'Content-Type: application/json' \
    -d '{"in_stock_amount":400}'

Notice the URI of the API endpoint is https://<store>.lemonstand.com/api/v2/product/1</store>. If the store you signed up with LemonStand is apples.lemonstand.com, you would make API calls to https://apples.lemonstand.com/api/v2.

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>.lemonstand.com/api/v2/orders?embed=customer.billingAddresses,customer.shippingAddresses \
    -H "Authorization: Bearer y5QNsEEGg8s9XqiQFuqGOB5a1zV22pGRFJgHgCbH" \

Pagination

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.

Schema

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.

YYYY-MM-DDTHH:MM:SSZ

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"
  }
}

Changelog

Data Summary
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.]