Quick Start
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 ofmystoreprefix
- click Save and close the environment modal.
- Create a new request.
GET
,https://<<domain_prefix>>.retail.lightspeed.app/api/2.0/retailer
- You can find the definition of this endpoint in the Lightspeed Retail (X-Series) API Specification.
- If you want to share this request in Postman, you should use Environment Variables to store the domain prefix separately.
- 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.
- Type:
- 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!
- You should now see the response body with a
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 ofmystoreprefix
- click Save and close the environment modal.
- Create a new Request.
GET
,https://<<domain_prefix>>.retail.lightspeed.app/api/2.0/retailer
- You can find the definition of this endpoint via the Lightspeed Retail (X-Series) API Specification.
- Select the Authorization tab.
- Type:
OAuth 2.0
- Click on
Get a new Access Token
.
- Type:
- 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)
- Grant Type:
- 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 theadmin
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'.
- You will then be asked to specify your Domain Prefix
- 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!
- You should now see the Response Body, containing a
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 5 months ago