API OAuth Scopes

Applications integrating with the X-series API must request the appropriate OAuth scopes during the retailer authorization step. Each scope grants permission to read and/or write a domain (or a portion of a domain) such as products, sales, customers, price books, or consignments. Every endpoint in the reference indicates its required scope(s). The scope set you request is presented to the retailer admin for review during authorization.

Selecting Scopes For Your Application

Review all endpoints used by your application.
Check the required scope(s) for each endpoint; combine them and remove duplicates to form your scope list.
Check field-access requirements too, and add scopes only for the protected fields your application needs.

Once identified, request these scopes by adding a space-delimited scope parameter to the authorization request (see Authorization reference). Example:

&scope=products:read sales:read customers:read

Minimize the scopes to only those needed by your application to reduce the chance a retailer admin declines connecting your app for requesting unnecessary access.

When an endpoint requires multiple scopes, request all of them. A field-access scope is different: it controls protected response fields without replacing the endpoint's required scopes. “No additional scope required” does not mean an endpoint is unauthenticated; a valid access token is still required.

It is strongly recommended to test your application end-to-end using tokens limited to the scopes you plan to request, to confirm it functions correctly with only those permissions.

Example

Suppose your app needs to:

List products (GET /api/{version}/products)
Fetch a single sale (GET /api/{version}/sales/{id})
Create a supplier purchase order (POST /api/{version}/consignments with type SUPPLIER)

Endpoint	Purpose	Required Scope(s)
GET /api/{version}/products	List products	products:read
GET /api/{version}/sales/{id}	Retrieve sale details	sales:read
POST /api/{version}/consignments (SUPPLIER)	Create supplier order	consignments:write:stock_order

Combined scope set (duplicates removed):

products:read sales:read consignments:write:stock_order

Authorization request (space-delimited scopes):

https://secure.retail.lightspeed.app/connect?response_type=code&client_id={client_id}&redirect_uri={redirect_uri}&state={state}&scope=products:read%20sales:read%20consignments:write:stock_order

Available Scopes

Scope	Description
audit:read	Read audit and security events
billing:partner_subscription:read	Read Billing Partner Subscription.
billing:partner_subscription:write	Write Billing Partner Subscription.
business_rules:read	Read business rules.
business_rules:write	Create and delete business rules.
channels:read	Read e-commerce channel information.
consignments:read	Read in-progress inventory counts and historical stock consignments.
consignments:write:inventory_count	Perform Inventory Counts.
consignments:write:stock_order	Process stock orders and stock returns.
consignments:write:stock_transfer	Create, send and receive stock transfers between outlets.
customers:read	Read customers and customer groups.
customers:write	Create, update and delete customers and customer groups.
custom_fields:read	Read custom fields.
custom_fields:write	Create, update and delete custom fields.
fulfillments:read	Read sale order fulfillments
fulfillments:write	Create and update sale order fulfillments.
gift_cards:read	Read gift cards and gift card transactions.
gift_cards:write:issue	Issue a gift card to a customer.
gift_cards:write:redeem	Redeem or reload an amount against a customers gift card.
inventory:read	Read current and historical product inventory levels.
inventory:write	Set reorder points, create custom inventory adjustment reasons, and record stock adjustments.
loyalty:write:transaction	Create loyalty transactions and bulk loyalty adjustments.
outlets:read	Read outlets.
payments:read	Read Payments.
payment_types:read	Read payment types, excluding internal payment types.
payment_types:write	Create, update and delete payment types.
products:read	Read products, product types, product images, brands and tags, excluding product costs.
products:read:costs	Read protected product supply prices, consignment costs and inventory costs.
products:read:price_books	Read product price books.
products:write	Create and update products (excluding product costs), delete products, upload product images and create product types.
products:write:price_books	Write Products Price Books.
promotions:read	Read promotions, get products a specific promotion can be used on and find the best promotion for a sale and determine the discount.
promotions:write	Create, update and archive any promotion.
register:close	Close a register and reconcile payments.
register:open	Open a register to create sales and payments.
registers:read	Read registers.
remote_rules:read	Read remote rules.
remote_rules:write	Create and delete remote rules.
retailer:read	Read all your account configuration. E.g. your loyalty ratio, timezone, country and currency.
sales:read	Read all sales and payments in your account.
sales:write	Create sales and payments, and adjust, void or return sales.
serial_numbers:read	Read serial numbers.
serial_numbers:write	Add and delete serial numbers.
services:read	Read services
services:write	Create, edit services.
store_credits:read	Read store credit transactions, overall and for customers.
store_credits:write:issue	Issue store credits to a customer manually or for a return.
store_credits:write:redeem	Redeem or reverse store credit transactions, and create or reverse store credit holds.
suppliers:read	Read suppliers.
suppliers:write	Create, update and delete suppliers.
taxes:read	If tax inclusive: Read tax rates and tax rules. If tax exclusive: Read tax rates, tax rules and tax groups.
taxes:write	Create, update and delete taxes.
users:read	Read user information (except user passwords).
users:write	Create, update and delete users and customise groups.
webhooks	Manage webhooks created by the application.