Tutorials

Quick Start

Suggest Edits

Quick Start

This quick start tutorial will provide you with simple steps to start using the Lightspeed Retail (X-Series) API.

You can think of this document as the 'Hello, World!' of Lightspeed Retail (X-Series)'s API. It will take you from zero to your first API request. Lightspeed Retail (X-Series)'s API can be used to extend Lightspeed Retail (X-Series)'s functionality, and to integrate with other software in the Retail ecosystem.

What you'll need

Please install Postman, or alternatively, use your favourite software development environment.

With simplicity in mind, we will use a GUI to connect to Lightspeed Retail (X-Series)'s API for this tutorial. Please feel free to use a software development platform instead, but this tutorial will use a GUI tool called Postman. By all means use your favourite software development platform in place of Postman, but software development tools are out of scope for this document.

Overview

  • Choose how to connect:
    • A. Personal Tokens: retailers can create a Personal Token.
    • B. Add-ons: independent developers should register as a Lightspeed Retail (X-Series) developer, and create an application.
      • For add-ons, set up a test retailer account, and then pair a retailer account with your application.
  • For both personal tokens and add-ons:
    • Consult the API documentation to discover API Endpoints.
    • Invoke the API using Postman, to retrieve some useful information about the retailer.
  • What Next?

Choose how to connect

There are two ways to work with Lightspeed Retail (X-Series)'s API - Personal Tokens and Add-ons. You can decide which to use, as follows:

  • A. Personal Tokens are for use by individual retailers (and their developers), to connect to that single Lightspeed Retail (X-Series) retailer account.
  • B. Add-ons are registered independently by developers, and can be connected to multiple retailers.
  • Add-ons and applications are interchangeable names. The Developer Portal uses the term 'application', but elsewhere, 'add-on' is used.

Head over to Authorization for a detailed reference about authentication and authorization.

A. Personal Tokens

As a retailer [Admin users only], you can use a Personal Token to access the API.

Even as an integrator, Personal Tokens can be used as a quick way to explore the API - you can set up a Test Store for testing, and then generate personal tokens to interact with that store.

Personal Tokens, Step 1 - Create a Personal Token

Create a Personal Token, and keep the token somewhere secure.

Personal Tokens, Step 2 - Connect to the API

Using Postman (please download and install it), you can configure the OAuth flow, as follows.

These instructions are correct as of Postman v7.20.1.

  • Recommendation: Create an Environment for your test store, with one variable domain_prefix=mystore
    • Click the Environment quick look (eye button) in the top right of Postman and click Edit next to Globals.
    • Add a variable named domain_prefix and give it a value of mystoreprefix - click Save and close the environment modal.
  • Create a new request. GET, https://<<domain_prefix>>.retail.lightspeed.app/api/2.0/retailer
  • Select the Authorization tab.
    • Type: Bearer Token
    • Token: (enter the Personal Token which you created in Step 1)
    • If you want to share this request in Postman, you should use Environment Variables to store the token separately. In this case, enter the variable {{personal_token}} here instead.
  • Click Send.
    • You should now see the response body with a JSON representation of the retailer entity associated with this account.
    • Congratulations, you are now a Lightspeed Retail (X-Series) API user!

B. Add-ons

As a developer - independent of retailers - you should consider registering yourself on our developer portal, and creating a Lightspeed Retail (X-Series) Application. Add-ons are also known as Lightspeed Retail (X-Series) applications.

This will provide you with a secured way to register your application with a retailer, and to grow your user-base.

Add-ons, Step 1 - Registration as a Developer and Create an application

To create an application, first of all you'll need to register as a Lightspeed Retail (X-Series) Developer.

Secondly, you will need to create an application. When you create an application, you will be asked to specify a 'Callback URL'.

Callback URL

The Callback URL is a page on your website which is intended to pair your application with a Lightspeed Retail (X-Series) retailer. See the Authorization page for more details.

For the purposes of this tutorial, when using Postman, it doesn't matter what you use, as long as it is a valid URL - it can just be 'http://example.org/callback'. Postman will intercept the OAuth 2.0 flow before following the redirect, and complete the steps itself. Postman is clever.

NOTE: _You will notice that a newly created app is marked as Not Approved. Don’t worry! You can still use this app. Not Approved just means that you can only connect your application to 30 Lightspeed Retail (X-Series) retailer accounts. This should be more than enough for private apps or testing/staging environments. You only need to get our approval for production ready, public applications._

The application will have 3 fields associated with it, a Redirect URL, a Client ID, and a Client Secret. We will need these in order to connect the application to a retailer, below.

Add-ons, Step 2 - set up a test store

As an integrator, you may want to set up a retailer account to test your software before shipping it to retailers.

Initially you can sign up for a trial store in the usual way.

Please contact [email protected] to discuss long-term requirements.

For the following steps, let's assume your test store's domain prefix is 'mystoreprefix', and stored in a Postman variable, {{domain_prefix}}.

Add-ons, Step 3 - Connect your application to the retailer account, and send a request.

In order to connect your add-on to a retailer, you need to perform the OAuth2 connection flow.

Typically an add-on initiates this flow, and the retailer will be presented with a 'Consent' screen.

Using Postman (please download and install it), you can configure the OAuth flow, as follows.

These instructions are correct as of Postman v7.20.1.

  • Recommendation: Create an Environment for your test store, with one variable domain_prefix=mystoreprefix
    • Click the Environment quick look (eye button) in the top right of Postman and click Edit next to Globals.
    • Add a variable named domain_prefix and give it a value of mystoreprefix - click Save and close the environment modal.
  • Create a new Request. GET, https://<<domain_prefix>>.retail.lightspeed.app/api/2.0/retailer
  • Select the Authorization tab.
    • Type: OAuth 2.0
    • Click on Get a new Access Token.
  • In the Get New Access Token dialog:
    • Grant Type: Authorization Code
    • Callback URL: (see Step 1). This would normally point to a URL hosted by you, the developer.
    • Auth URL: https://secure.retail.lightspeed.app/connect
    • Access Token URL: https://<<domain_prefix>>.retail.lightspeed.app/api/1.0/token
    • Client ID: (see Add-ons, Step 1)
    • Client Secret: (see Add-ons, Step 1)
    • Scope: [blank]
    • State: a unique, randomly generated, opaque, and non-guessable string (see more details on the authorization section)
  • Click Request Token.
    • You will then be asked to specify your Domain Prefix {{domain_prefix}}, and then log into your retailer credentials. This will need to be any user with the admin role.
    • You will then be asked to 'Connect to the Application'.
    • Finally, you will be redirected back to Postman. You'll see a dialog showing your token, with 'Access Token', 'Type: Bearer', expires_in: 259200 (the number of seconds is subject to change), your domain prefix, and a 'Refresh Token'.
  • Click Use Token.
    • The dialog will now close.
  • Click Send.
    • You should now see the Response Body, containing a JSON representation of the retailer entity for your account.
    • Congratulations, you are now a Lightspeed Retail (X-Series) API user!

Postman Tips

Postman allows you to keep your auth and retailer information separate from your API call definitions. See Postman's article on variables. Variables can have different scopes - Environment scope keeps your scripts independent of security or retailer information.

This is important for security (especially if sharing postman scripts), and for accessing different retailer accounts.

  • For security reasons, do NOT include personal tokens directly in an API call. Keep them as Environment variables, and reference them as {{personal_token}}.
  • Likewise, use a {{domain_prefix}} variable for testing different retailers.

What Next?

Now that you know how to access Lightspeed Retail (X-Series)'s API, please explore the documentation - we recommend returning to the Introduction document.

Postman is a useful tool for exploring the API, but add-on developers normally need to perform some extra steps to work with OAuth (unless using a platform like Zapier, which supports OAuth2 already):

  • Add-on developers will usually need some extra work to manage tokens and registration. Unless you are using a packaged platform like Zapier (or Lightspeed Retail (X-Series) Personal Tokens), you will need to implement an OAuth 2.0 client.
    • The Redirect URL should be a dynamic web page hosted by you, the developer. It should be designed to interpret an OAuth 2.0 Code Grant.
    • The Redirect URL processes the redirect according to the OAuth 2.0 spec, and then invoke Lightspeed Retail (X-Series)'s /api/1.0/token endpoint.
    • The add-on needs to securely store an access token and a refresh token for each retailer.
    • The add-on needs to handle access token expiry and refreshing of tokens (again, according to the OAuth 2 standard). Depending on your technology platform, there may be a library which you can use for this. Even if not, it's feasible to write the handler yourself.
    • Refer to Authorization for a more detailed reference for these steps.
  • Typically an add-on invokes the API several times, using the data from one response in subsequent requests.

For more Postman tips, please check the Postman documentation.

Updated 8 months ago