# Lightspeed Retail (X-Series) API Documentation Hub Documentation > Documentation for Lightspeed Retail (X-Series) API Documentation Hub ## Guides - [Introduction to the Lightspeed Retail (X-Series) API](https://x-series-api.lightspeedhq.com/docs/introduction.md) - [Authorization](https://x-series-api.lightspeedhq.com/docs/authorization.md) - [Versioning Strategy](https://x-series-api.lightspeedhq.com/docs/versioning-strategy.md) - [OAuth Scopes](https://x-series-api.lightspeedhq.com/docs/scopes.md) - [Data Security](https://x-series-api.lightspeedhq.com/docs/data_security.md) - [User Agent](https://x-series-api.lightspeedhq.com/docs/user_agent.md) - [Rate Limiting](https://x-series-api.lightspeedhq.com/docs/rate_limiting.md) - [Pagination](https://x-series-api.lightspeedhq.com/docs/pagination.md) - [Request Format](https://x-series-api.lightspeedhq.com/docs/request_format.md) - [Dates and Times](https://x-series-api.lightspeedhq.com/docs/dates_and_times.md) - [Outbound Request Origins](https://x-series-api.lightspeedhq.com/docs/outbound_request_origins.md) - [Quick Start](https://x-series-api.lightspeedhq.com/docs/quick_start.md) - [How to React to Lightspeed Retail (X-Series) Events](https://x-series-api.lightspeedhq.com/docs/reacting_to_vend_events.md) - [Syncing an Entity to an External System](https://x-series-api.lightspeedhq.com/docs/sync_entity_to_external_system.md) - [Synchronizing Sales from External Systems into Lightspeed Retail (X-Series)](https://x-series-api.lightspeedhq.com/docs/sync_sale_into_vend.md) - [Fulfillments](https://x-series-api.lightspeedhq.com/docs/fulfillments_partial_fulfillment.md) - [Gift Cards](https://x-series-api.lightspeedhq.com/docs/gift_cards.md) - [Creating Inventory Counts](https://x-series-api.lightspeedhq.com/docs/inventory_creating_inventory_counts.md) - [Creating Stock Orders](https://x-series-api.lightspeedhq.com/docs/inventory_creating_stock_orders.md) - [Inventory Updates](https://x-series-api.lightspeedhq.com/docs/inventory_updates.md) - [Loyalty 101](https://x-series-api.lightspeedhq.com/docs/loyalty_101.md) - [Pricebooks](https://x-series-api.lightspeedhq.com/docs/pricebooks.md) - [Creating Composite Products](https://x-series-api.lightspeedhq.com/docs/products_creating_composites.md) - [Updating Composite Products](https://x-series-api.lightspeedhq.com/docs/products_updating_composites.md) - [Image Upload Basics](https://x-series-api.lightspeedhq.com/docs/products_image_upload_basics.md) - [Image Upload Code Sample - Golang](https://x-series-api.lightspeedhq.com/docs/products_image_uploads_code_sample_go.md) - [Image Upload Code Sample - Java with Jersey](https://x-series-api.lightspeedhq.com/docs/products_image_uploads_code_sample_java_jersey.md) - [Image Upload Code Sample - JavaScript with Request](https://x-series-api.lightspeedhq.com/docs/products_image_uploads_code_sample_javascript_request.md) - [Image Upload Code Sample - JavaScript with Superagent](https://x-series-api.lightspeedhq.com/docs/products_image_uploads_code_sample_javascript_superagent.md) - [Image Upload Code Sample - PHP with Guzzle](https://x-series-api.lightspeedhq.com/docs/products_image_uploads_code_sample_php_guzzle.md) - [Image Upload Code Sample - Python with Requests](https://x-series-api.lightspeedhq.com/docs/products_image_uploads_code_sample_python_requests.md) - [Image Upload Code Sample - Ruby with Typhoeus](https://x-series-api.lightspeedhq.com/docs/products_image_uploads_code_sample_ruby_typhoeus.md) - [Variants](https://x-series-api.lightspeedhq.com/docs/products_variants.md) - [Creating Variants](https://x-series-api.lightspeedhq.com/docs/products_variants_creating_variants.md) - [Updating Variants](https://x-series-api.lightspeedhq.com/docs/products_variants_update.md) - [Promotions](https://x-series-api.lightspeedhq.com/docs/promotions.md) - [Closing](https://x-series-api.lightspeedhq.com/docs/registers_closing.md) - [Sales 101](https://x-series-api.lightspeedhq.com/docs/sales_101.md) - [Discounts](https://x-series-api.lightspeedhq.com/docs/sales_discounts.md) - [Editing Sales](https://x-series-api.lightspeedhq.com/docs/sales_editing_sales.md) - [Fulfillments](https://x-series-api.lightspeedhq.com/docs/sales_fulfillments.md) - [Returns](https://x-series-api.lightspeedhq.com/docs/sales_returns.md) - [Sales with Services](https://x-series-api.lightspeedhq.com/docs/sales_service_sales.md) - [States and attributes](https://x-series-api.lightspeedhq.com/docs/sales_states_and_attributes.md) - [Statuses](https://x-series-api.lightspeedhq.com/docs/sales_statuses.md) - [Delivery Sales with Customer Addresses](https://x-series-api.lightspeedhq.com/docs/sales_delivery_with_addresses.md) - [Migrating from v0.9 to date-based API](https://x-series-api.lightspeedhq.com/docs/sales_migration_guide.md) - [Decoding a Barcode to a Sale UUID](https://x-series-api.lightspeedhq.com/docs/sales_barcode_decode.md) - [Introduction](https://x-series-api.lightspeedhq.com/docs/service_orders_introduction.md) - [Store Credit](https://x-series-api.lightspeedhq.com/docs/store_credit.md) - [Webhooks](https://x-series-api.lightspeedhq.com/docs/webhooks.md) - [Webhooks - Example Payloads](https://x-series-api.lightspeedhq.com/docs/webhooks_example_payloads.md) - [Business Rules](https://x-series-api.lightspeedhq.com/docs/workflows_business_rules.md) - [Custom Fields](https://x-series-api.lightspeedhq.com/docs/workflows_custom_fields.md) - [Redirect API](https://x-series-api.lightspeedhq.com/docs/redirect_api.md) - [Outlet Hooks](https://x-series-api.lightspeedhq.com/docs/client_api_outlet_hooks.md) - [Reference](https://x-series-api.lightspeedhq.com/docs/client_api_reference.md) - [Register Hooks](https://x-series-api.lightspeedhq.com/docs/client_api_register_hooks.md) - [Sale Hooks](https://x-series-api.lightspeedhq.com/docs/client_api_sale_hooks.md) - [Getting Started](https://x-series-api.lightspeedhq.com/docs/payments_api_getting_started.md) - [Pairing Flow](https://x-series-api.lightspeedhq.com/docs/payments_api_pairing_flow.md) - [Reference](https://x-series-api.lightspeedhq.com/docs/payments_api_reference.md) - [Activating a Subscription](https://x-series-api.lightspeedhq.com/docs/third_party_billing_activating_a_subscription.md) - [Canceling a Subscription](https://x-series-api.lightspeedhq.com/docs/third_party_billing_canceling_a_subscription.md) - [Updating an Existing Subscription](https://x-series-api.lightspeedhq.com/docs/third_party_billing_updating_an_existing_subscription.md) - [2026-04](https://x-series-api.lightspeedhq.com/docs/2026-04-release-notes.md) - [2026-07](https://x-series-api.lightspeedhq.com/docs/2026-07-release-notes.md) ## API Reference - [List audit events](https://x-series-api.lightspeedhq.com/reference/getauditlogevents.md): This API returns a list of all the audit log events that match the given filters. **Note**: Not every single change in the system is audited. Currently the audited entities include: | Object | Action | Notes | |------------|---------------------------|-------| | customer | form create/update/delete | | | customer | api create/update/delete | | | customer | csv import | | | register | form create/update/delete | | | outlet | form create/update/delete | | | csv import | init | Tracks CSV import requests and includes data about the import type (customer, product) and the CSV file line count. | | product* | create/update/delete | All actions on products. | | security | terms_accepted, signin, signout, change_email, change_password, reset_password_confirm, user_switching_succes, user_switching_denied, new_personal_token, update_personal_token, delete_personal_tokenss, issue_oauth_token || | vend_consignment | insert/update | Receiving, creating and editing purchase orders as well as inventory counts. | | vend_consignment_product | insert/update | Changes to the products in a purchase order. Such as creating purchase orders. | | timeclock | clockin/clockout | Clock event where a user either clocked in or clocked out. | ### Filters - The from and to filters require a full isoformat date, for example `?from=2020-02-03T00:00:00&to=2020-02-05T23:59:59`. 🔒 Requires: `audit:read` scope - [List security events for current user](https://x-series-api.lightspeedhq.com/reference/get-security_events.md): This API returns a list of all the security log events **for the current user**. If you want a list of all the security events for all users please use the auditlog_events with filter type == "security". See the auditlog_events API in the beta documentation for more information. 🔒 Requires: `audit:read` scope - [List brands](https://x-series-api.lightspeedhq.com/reference/listbrands.md): Returns a paginated list of brands. 🔒 Requires: `products:read` scope - [Create brand](https://x-series-api.lightspeedhq.com/reference/createbrand.md): Creates a new brand. 🔒 Requires: `products:write` scope - [Delete a single brand](https://x-series-api.lightspeedhq.com/reference/deletebrandbyid.md): Deletes a brand. If there are products associated with the brand, the products will be disassociated from the brand. 🔒 Requires: `products:write` scope - [Get a single brand](https://x-series-api.lightspeedhq.com/reference/getbrandbyid.md): Returns a single brand with a requested ID 🔒 Requires: `products:read` scope - [Update a single brand](https://x-series-api.lightspeedhq.com/reference/updatebrandbyid.md): 🔒 Requires: `products:write` scope - [List request records](https://x-series-api.lightspeedhq.com/reference/listrequests.md): Returns a list of request log records. 🔒 Requires: `channels:read` scope - [Get a single request log](https://x-series-api.lightspeedhq.com/reference/getsinglerequest.md): Returns a single request log entry with a specific ID. 🔒 Requires: `channels:read` scope - [Get a single request log as text](https://x-series-api.lightspeedhq.com/reference/getsinglerequesttext.md): Returns a text representation of a single request log entry with a specific ID. 🔒 Requires: `channels:read` scope - [List channel records](https://x-series-api.lightspeedhq.com/reference/listchannels.md): Returns a list of configured channels. 🔒 Requires: `channels:read` scope - [Bulk update consignment products](https://x-series-api.lightspeedhq.com/reference/createorupdateconsignmentproducts.md): Add or update the products in a consignment in bulk. **Note**: Must include either count or received for each product. **Note**: It is not recommended to update more than 500 products at a time, as this may lead to server timeouts. **Note**: If the type is SUPPLIER then: - Cannot add a composite product by this api - Cannot update products if the consignment has a status of RECEIVED or CANCELLED - If status is OPEN or SENT, the count value will be accumulated - If status is DISPATCHED, the received quantity will be accumulated - If status is OPEN, SENT or DISPATCHED, the cost will be updated - If a received field is provided for consignment products in an OPEN or SENT Supplier Order - the order will be automatically marked as DISPATCHED. Remove the received field if you don't intend to dispatch the OPEN or SENT purchase order 🔒 Requires: One of the following scopes: - `consignments:write:stock_order` scope for `SUPPLIER` and `RETURN` consignments - `consignments:write:stock_transfer` scope for `OUTLET` consignments - `consignments:write:inventory_count` scope for `STOCKTAKE` consignments - [List all products for a specific consignment](https://x-series-api.lightspeedhq.com/reference/listproductsbyconsignmentid.md): Returns a collection of consignment products associated with the specified consignment. 🔒 Requires: `consignments:read` scope - [Add a product to a consignment](https://x-series-api.lightspeedhq.com/reference/createconsignmentproduct.md): Add a product to the given consignment. If the type is SUPPLIER then: - Cannot add a product to a `RECEIVED` or `CANCELLED` order - Cannot add a composite product to the order - If a received value is provided for a consignment product for a SENT Supplier Order - the order will be automatically marked as DISPATCHED If the type is OUTLET then: - If a cost value is not provided for a consignment product on an OPEN Outlet order - the cost will be automatically populated after the fact using the most accurate average cost of the product at the time of marking the consignment as sent. 🔒 Requires: One of the following scopes: - `consignments:write:stock_order` scope for `SUPPLIER` and `RETURN` consignments - `consignments:write:stock_transfer` scope for `OUTLET` consignments - `consignments:write:inventory_count` scope for `STOCKTAKE` consignments - [Delete an item from a consignment](https://x-series-api.lightspeedhq.com/reference/deleteproductfromconsignment.md): Removes the specific product from the consignment. For `SUPPLIER` workflow: - Cannot delete a product from a consignment with a status of `DISPATCHED`, `RECEIVED` or `CANCELLED` For consignment type `OUTLET`: - Cannot delete a product if the consignment has a status of `SENT` or `RECEIVED` For consignment type `RETURN`: - Cannot delete a product if the consignment has a status of `SENT` 🔒 Requires: One of the following scopes: - `consignments:write:stock_order` scope for `SUPPLIER` and `RETURN` consignments - `consignments:write:stock_transfer` scope for `OUTLET` consignments - `consignments:write:inventory_count` scope for `STOCKTAKE` consignments - [Update a product in a consignment](https://x-series-api.lightspeedhq.com/reference/updateproductinconsignment.md): Updates the specific product within the consignment. **Notes**: - If the type is SUPPLIER then: * If status is OPEN or SENT, the count value will be updated * If status is DISPATCHED, the received quantity will be updated * If status is OPEN, SENT or DISPATCHED, the cost can be updated * Cannot update a product in RECEIVED or CANCELLED status * Any updates to the received quantity field on a product in a `SENT` consignment, will set the consignment status to `DISPATCHED` - If the type is OUTLET then: * If the status is OPEN and there is a cost the cost will be updated. * If the status is SENT or DISPATCHED and received is not null the received quantity will be updated. * If the status is OPEN or SENT and count is not null then the count quantity will be updated. - If the type is RETURN and the status is OPEN or SENT and count is not null then the count quantity will be updated. - If the type is STOCKTAKE and the status is STATUS\_STOCKTAKE\_IN\_PROGRESS or STATUS\_STOCKTAKE\_IN\_PROCESS\_PROCESSED and received is not null then the received quantity will be updated. 🔒 Requires: One of the following scopes: - `consignments:write:stock_order` scope for `SUPPLIER` and `RETURN` consignments - `consignments:write:stock_transfer` scope for `OUTLET` consignments - `consignments:write:inventory_count` scope for `STOCKTAKE` consignments - [List consignments](https://x-series-api.lightspeedhq.com/reference/getconsignments.md): Return a paginated list of consignments. 🔒 Requires: `consignments:read` scope - [Create a consignment](https://x-series-api.lightspeedhq.com/reference/createconsignment.md): Creates a new consignment. The consignment type can be `SUPPLIER`, `OUTLET`, `STOCKTAKE` or `RETURN`. The workflows for these are: - `SUPPLIER` workflow: `OPEN` -> `SENT` -> `DISPATCHED` -> `RECEIVED` * Can be `CANCELLED` at any time, except from `RECEIVED` * Cannot create a `DISPATCHED` or `RECEIVED` consignment directly * In the response `reference` refers to `Order number` and `name` refers to `Note` - `OUTLET` workflow: `OPEN` -> `SENT` -> `RECEIVED` (can be `CANCELLED` at any time after `OPEN`) - `RETURN` workflow: `OPEN` -> `SENT` or `CANCELLED` - `STOCKTAKE` workflow: `STOCKTAKE` or `STOCKTAKE_SCHEDULED` -> `STOCKTAKE_IN_PROGRESS` -> `STOCKTAKE_IN_PROGRESS_PROCESSED` -> `STOCKTAKE_COMPLETE` (can be `CANCELLED` or `CLOSED` at any time) 🔒 Requires: One of the following scopes: - `consignments:write:stock_order` scope for `SUPPLIER` and `RETURN` consignments - `consignments:write:stock_transfer` scope for `OUTLET` consignments - `consignments:write:inventory_count` scope for `STOCKTAKE` consignments - [Delete a consignment](https://x-series-api.lightspeedhq.com/reference/deleteconsignmentbyid.md): Deletes the consignment with the given ID. 🔒 Requires: One of the following scopes: - `consignments:write:stock_order` scope for `SUPPLIER` and `RETURN` consignments - `consignments:write:stock_transfer` scope for `OUTLET` consignments - `consignments:write:inventory_count` scope for `STOCKTAKE` consignments - [Get a single consignment](https://x-series-api.lightspeedhq.com/reference/getconsignmentbyid.md): Returns a single consignment with the requested ID. 🔒 Requires: `consignments:read` scope - [Update a consignment](https://x-series-api.lightspeedhq.com/reference/updateconsignmentbyid.md): Updates the given consignment. If the type is SUPPLIER then: - Cannot change from `SUPPLIER` to a different consignment type - `SUPPLIER` workflow: `OPEN` -> `SENT` -> `DISPATCHED` -> `RECEIVED` - Can be `CANCELLED` at any time, except from `RECEIVED` - Cannot update a `SUPPLIER` consignment that has the status `RECEIVED` or `CANCELLED` - Cannot update status if there are no products in the order - At least one product should have non-zero received quantity before updating to `RECEIVED` 🔒 Requires: One of the following scopes: - `consignments:write:stock_order` scope for `SUPPLIER` and `RETURN` consignments - `consignments:write:stock_transfer` scope for `OUTLET` consignments - `consignments:write:inventory_count` scope for `STOCKTAKE` consignments - [Get consignment totals](https://x-series-api.lightspeedhq.com/reference/listconsignmenttotals.md): Returns the count and cost for the given consignment. The consignment type can be `SUPPLIER`, `OUTLET` or `RETURN` (not `STOCKTAKE`). The status of the consignment will determine which values make sense: - If the consignment type is `OUTLET` the sent cost may not be accurate when the status is `OPEN`. - If the consignment is `OPEN` or `SENT` the received count and cost should both be zero. - For completely received consignments received cost should equal the sent cost and the received count should equal the sent count. - For partially received consignments we would expect the received cost value to be less than sent cost value, and the received count to be less than the sent count. 🔒 Requires: `consignments:read` scope - [List all addresses for a customer](https://x-series-api.lightspeedhq.com/reference/listcustomeraddresses.md): Returns a list of all addresses associated with the specified customer. 🔒 Requires: `customers:read` scope - [Create a new address for a customer](https://x-series-api.lightspeedhq.com/reference/createcustomeraddress.md): Creates a new address for the specified customer. **Validation Rules:** - `country_code`: Required, must be a valid ISO 3166-1 alpha-2 code (e.g., US, NZ, AU) - `state_code`: Required for US and CA, must be valid for the country - `postcode`: Required, must be valid format for the country - `type`: Required, must be either BILLING or SHIPPING - `address_line_1`: Required, maximum 50 characters - `city`: Required, maximum 28 characters - `state`: Maximum 35 characters 🔒 Requires: `customers:write` scope - [Delete an address](https://x-series-api.lightspeedhq.com/reference/deletecustomeraddress.md): Deletes an address for the specified customer. 🔒 Requires: `customers:write` scope - [Get a single address](https://x-series-api.lightspeedhq.com/reference/getcustomeraddress.md): Returns a single address by its ID for the specified customer. 🔒 Requires: `customers:read` scope - [Update an address](https://x-series-api.lightspeedhq.com/reference/updatecustomeraddress.md): Updates an existing address for the specified customer. **Validation Rules:** - `country_code`: Required, must be a valid ISO 3166-1 alpha-2 code (e.g., US, NZ, AU) - `state_code`: Required for US and CA, must be valid for the country - `postcode`: Required, must be valid format for the country - `type`: Required, must be either BILLING or SHIPPING - `address_line_1`: Required, maximum 50 characters - `city`: Required, maximum 28 characters - `state`: Maximum 35 characters 🔒 Requires: `customers:write` scope - [List customer groups](https://x-series-api.lightspeedhq.com/reference/listcustomergroups.md): Return a list of Customer Groups 🔒 Requires: `customers:read` scope - [Create new customer group](https://x-series-api.lightspeedhq.com/reference/createcustomergroup.md): Create a new customer group 🔒 Requires: `customers:write` scope - [Get single customer group](https://x-series-api.lightspeedhq.com/reference/getcustomergroupbyid.md): Return given customer group 🔒 Requires: `customers:read` scope - [Update the given customer group](https://x-series-api.lightspeedhq.com/reference/updatecustomergroup.md): Update the given Customer Group 🔒 Requires: `customers:write` scope - [Delete customers from customer group](https://x-series-api.lightspeedhq.com/reference/deletecustomersfromcustomergroup.md): Deletes the given customers from the customer group. **Note**: Only the link is deleted, the customers are not. 🔒 Requires: `customers:write` scope - [Get customers for customer group](https://x-series-api.lightspeedhq.com/reference/getcustomergroupcustomers.md): Returns a list of customers for the given Customer Group 🔒 Requires: `customers:read` scope - [Add customers to customer group](https://x-series-api.lightspeedhq.com/reference/addcustomerstocustomergroup.md): Associates one or more customers with the given customer group 🔒 Requires: `customers:write` scope - [List customers](https://x-series-api.lightspeedhq.com/reference/listcustomers.md): Returns a paginated list of customers. To search for customers, please have a look at our [Search endpoint](/reference/search-1) on what is supported. 🔒 Requires: `customers:read` scope - [Create a new customer](https://x-series-api.lightspeedhq.com/reference/createcustomer.md): Creates a new customer. 🔒 Requires: `customers:write` scope - [Delete a customer](https://x-series-api.lightspeedhq.com/reference/deletecustomerbyid.md): Deletes the customer with the requested ID. 🔒 Requires: `customers:write` scope - [Get a single customer](https://x-series-api.lightspeedhq.com/reference/getcustomerbyid.md): Returns a single customer with a requested ID. 🔒 Requires: `customers:read` scope - [Update a customer](https://x-series-api.lightspeedhq.com/reference/updatecustomerbyid.md): Updates the customer with the requested ID. 🔒 Requires: `customers:write` scope - [Get Fulfillments Summary](https://x-series-api.lightspeedhq.com/reference/getfulfillmentsummary.md): Retrieves a paginated list of fulfillment summary items with optional filtering - [Fulfill a Sale](https://x-series-api.lightspeedhq.com/reference/postfulfillsale.md): Completes all fulfillments for a given sale. This is an idempotent action. 🔒 Requires: `sales:write` scope - [Fulfill line items within a sale](https://x-series-api.lightspeedhq.com/reference/postfulfilllineitems.md): Fulfills line items for a given sale. This is an idempotent action. Each line item may optionally include a `source_breakdown`, which specifies how a fulfillment quantity should be sourced. When provided, all three fields are required and must sum to the parent quantity. 🔒 Requires: `sales:write` scope - [Get Fulfillment History](https://x-series-api.lightspeedhq.com/reference/getfulfillmenthistory.md): Retrieves the history ledger for a single fulfillment, showing all state-change events (e.g. created, picked, packed, fulfilled, voided, returned) for each line item. Results are ordered oldest-first and support cursor-based pagination. When no more pages exist, the `next_cursor` field will be empty. 🔒 Requires: `fulfillments:read` scope - [Partial Pack line items within a sale](https://x-series-api.lightspeedhq.com/reference/postpacklineitems.md): Sets pack quantity for line items for a given sale. This is an idempotent action. Each line item may optionally include a `source_breakdown`, which specifies how a packing quantity should be sourced. When provided, both fields are required and must sum to the parent quantity. Source breakdown is not allowed when the quantity is negative (unpacking). 🔒 Requires: `sales:write` scope - [Partial Pick line items within a sale](https://x-series-api.lightspeedhq.com/reference/postpicklineitems.md): Sets pick quantity for line items for a given sale. This is an idempotent action. 🔒 Requires: `sales:write` scope - [List gift cards](https://x-series-api.lightspeedhq.com/reference/listgiftcards.md): Returns a paginated list of gift cards. 🔒 Requires: `gift_cards:read` scope - [Create gift card](https://x-series-api.lightspeedhq.com/reference/creategiftcard.md): Creates and activates a new gift card. The gift card will be created with one transaction with status "ACTIVATION" which contains the initial balance of the gift card. 🔒 Requires: `gift_cards:write:issue` scope - [Void gift card by id](https://x-series-api.lightspeedhq.com/reference/voidgiftcardbyid.md): Voids the gift card with the given id. The gift card balance will be set to zero and its status changed to "VOIDED". 🔒 Requires: `gift_cards:write:issue` scope - [Find gift card by id](https://x-series-api.lightspeedhq.com/reference/findgiftcardbyid.md): Finds and returns the gift card with the given id. Returns a 404 if the card does not exist. Within the gift card structure returned is the field `gift_card_transactions` which contains a list of all the transactions associated with the gift card. In this list you will see one or more of the following statuses: * "ACTIVATION" - This transaction type is added automatically when the gift card is created. The amount will be the initial balance that was loaded onto the gift card. * "REDEEMING" - This status indicates the customer used their gift card to pay for one or more items. The amount MUST be negative. * "IMPORTING" - You should only see this if gift cards were imported into the gift card system. * "VOIDING" - You will see this status if the gift card has been voided. Note that the balance of the card is set to zero when the gift card is voided. * "EXPIRING" - This transaction is added automatically when the gift card expires. Again note that the balance is set to zero when the gift card expires. * "REVERSING" - This status indicates that a given transaction was reversed. * "RELOADING" - This status means that more credit was loaded onto the gift card. 🔒 Requires: `gift_cards:read` scope - [Void gift card by number](https://x-series-api.lightspeedhq.com/reference/voidgiftcardbynumber.md): Voids the gift card with the given card number. The gift card balance will be set to zero and its status changed to "VOIDED". 🔒 Requires: `gift_cards:write:issue` scope - [Find gift card by number](https://x-series-api.lightspeedhq.com/reference/findgiftcardbynumber.md): Finds and returns the gift card with the given card number. Returns a 404 if the card does not exist. Within the gift card structure returned is the field `gift_card_transactions` which contains a list of all the transactions associated with the gift card. In this list you will see one or more of the following statuses: * "ACTIVATION" - This transaction type is added automatically when the gift card is created. The amount will be the initial balance that was loaded onto the gift card. * "REDEEMING" - This status indicates the customer used their gift card to pay for one or more items. The amount MUST be negative. * "IMPORTING" - You should only see this if gift cards were imported into the gift card system. * "VOIDING" - You will see this status if the gift card has been voided. Note that the balance of the card is set to zero when the gift card is voided. * "EXPIRING" - This transaction is added automatically when the gift card expires. Again note that the balance is set to zero when the gift card expires. * "REVERSING" - This status indicates that a given transaction was reversed. * "RELOADING" - This status means that more credit was loaded onto the gift card. 🔒 Requires: `gift_cards:read` scope - [Reverse gift card transaction](https://x-series-api.lightspeedhq.com/reference/reversegiftcardtransaction.md): Reverses the given transaction on the gift card. If the reversal is successful, a new transaction will be added to the gift card transactions with the status "REVERSING". Only transactions of type "REDEEMING" can be reversed. 🔒 Requires: `gift_cards:write:redeem` scope - [Find gift card by transaction id](https://x-series-api.lightspeedhq.com/reference/findgiftcardbytransactionid.md): Finds and returns the gift card associated with the given transaction id. Returns a 404 if the gift card with the given transaction id was not found. Supports an optional `system_id` query parameter to specify the source system (defaults to x-series, also supports e-series). 🔒 Requires: `gift_cards:read` scope - [Create a gift card transaction](https://x-series-api.lightspeedhq.com/reference/creategiftcardtransaction.md): Creates a new gift card transaction on the specified gift card. The request body requires the `type`, `amount`, and `client_id` fields. The `type` determines what sort of transaction it is. * "REDEEMING" - Use this type when you want to redeem a certain amount from the gift card balance. The amount MUST be negative. If you want to add an amount to the balance use the "RELOADING" type. * "RELOADING" - Use this type when you load a new amount onto a gift card. If the gift card does not have enough credit to honour the transaction a 422 HTTP status code will be returned. ## Idempotency Please populate the client_id field with a unique transaction identifier, to ensure that the transaction is safe from double-submit problems. See [the tutorial](/docs/gift_cards#idempotency) for more information. 🔒 Requires: `gift_cards:write:redeem` scope - [Void gift card](https://x-series-api.lightspeedhq.com/reference/voidgiftcard.md): Void the given gift card. 🔒 Requires: `gift_cards:write:issue` scope - [Find gift card](https://x-series-api.lightspeedhq.com/reference/findgiftcard.md): Finds and returns the given card number. Returns a 404 if the card does not exist. Within the gift card structure returned is the field gift__card__transactions which contains a list of all the transactions associated with the gift card. In this list you will see one or more of the following statuses: * "ACTIVATION" - This transaction type is added automatically when the gift card is created. The amount will be the initial balance that was loaded onto the gift card. * "REDEEMING" - This status indicates the customer used their gift card to pay for one or more items. The amount MUST be negative. * "IMPORTING" - You should only see this if gift cards were imported into the gift card system. * "VOIDING" - You will see this status if the gift card has been voided. Note that the balance of the card is set to zero when the gift card is voided. * "EXPIRING" - This transaction is added automatically when the gift card expires. Again note that the balance is set to zero when the gift card expires. * "REVERSING" - This status indicates that a given transaction was reversed. * "RELOADING" - This status means that more credit was loaded onto the gift card. 🔒 Requires: `gift_cards:read` scope - [List custom inventory adjustment reasons](https://x-series-api.lightspeedhq.com/reference/listcustominventoryadjustmentreasons.md): Returns a paginated list of custom inventory adjustment reasons for the authenticated retailer. 🔒 Requires: `inventory:write` scope - [Create a custom inventory adjustment reason](https://x-series-api.lightspeedhq.com/reference/createcustominventoryadjustmentreason.md): Creates a new custom inventory adjustment reason for the authenticated retailer. 🔒 Requires: `inventory:write` scope - [Update a custom inventory adjustment reason](https://x-series-api.lightspeedhq.com/reference/updatecustominventoryadjustmentreason.md): Updates a custom inventory adjustment reason. 🔒 Requires: `inventory:write` scope - [List inventory records](https://x-series-api.lightspeedhq.com/reference/listinventoryrecords.md): Returns a paginated list of inventory records. 🔒 Requires: `inventory:read` scope - [Set reorder points](https://x-series-api.lightspeedhq.com/reference/setreorderpoints.md): Sets reorder points for one or more products at specific outlets. The method must be consistent across all outlets for a product and within the same variant family. 🔒 Requires: `inventory:write` scope - [List inventory records for a single product](https://x-series-api.lightspeedhq.com/reference/listproductinventoryrecords.md): Returns inventory records for a single product at all outlets. 🔒 Requires: `inventory:read` scope - [List inventory levels](https://x-series-api.lightspeedhq.com/reference/listinventorylevels.md): Returns a paginated list of inventory levels. 🔒 Requires: `inventory:read` scope - [List inventory levels for a single product.](https://x-series-api.lightspeedhq.com/reference/listproductinventorylevels.md): Returns a paginated list of inventory levels for a single product. 🔒 Requires: `inventory:read` scope - [List stock adjustments](https://x-series-api.lightspeedhq.com/reference/liststockadjustments.md): Returns a paginated list of stock adjustments for the authenticated retailer. 🔒 Requires: `inventory:write` scope - [Create stock adjustments](https://x-series-api.lightspeedhq.com/reference/createstockadjustments.md): Creates one or more stock adjustments in a single batch (1–1000 items per request). 🔒 Requires: `inventory:write` scope - [List outlet product taxes](https://x-series-api.lightspeedhq.com/reference/listoutletproducttaxes.md): Returns a paginated list of outlet-product-tax records. 🔒 Requires: `outlets:read` scope - [List outlets](https://x-series-api.lightspeedhq.com/reference/listoutlets.md): Returns a collection of outlets. 🔒 Requires: `outlets:read` scope - [Get a single outlet](https://x-series-api.lightspeedhq.com/reference/getoutletbyid.md): Returns a single outlet with the requested ID. 🔒 Requires: `outlets:read` scope - [Render Packing Slip](https://x-series-api.lightspeedhq.com/reference/getpackingslip.md): Renders a packing slip for a fulfillment as an HTML document (which can be printed or converted to PDF). A packing slip lists the items to be packed and shipped for a fulfillment, along with the customer delivery address and any relevant serial number custom fields. Use the optional `lang` query parameter to control the language of the static template strings (labels and headings). When omitted or invalid, the packing slip defaults to `en-US`. 🔒 Requires: `sales:read` scope - [Render Partial Packing Slip](https://x-series-api.lightspeedhq.com/reference/getpartialpackingslip.md): Renders a partial packing slip for a fulfillment as an HTML document (which can be printed or converted to PDF). Unlike the full packing slip, a partial packing slip includes only the specified subset of sale line items and the exact quantities being packed. This is useful when a fulfillment is shipped across multiple parcels or in multiple stages. Each entry in `packed_line_items` must reference a valid sale line item and specify a positive quantity that does not exceed the quantity already packed on the pick lists. Use the optional `lang` field to control the language of the static template strings. When omitted or invalid, the packing slip defaults to `en-US`. 🔒 Requires: `sales:read` scope - [List partner subscriptions](https://x-series-api.lightspeedhq.com/reference/partnersubscriptions.md): Returns list of partner's subscriptions of the retailer 🔒 Requires: `billing:partner_subscription:read` scope - [Get a partner subscription](https://x-series-api.lightspeedhq.com/reference/partnersubscription.md): Returns a specific partner subscription of the retailer 🔒 Requires: `billing:partner_subscription:read` scope - [Create a partner subscription token](https://x-series-api.lightspeedhq.com/reference/partnertoken.md): Creates a partner subscription token (called by partner using retailer's access token) 🔒 Requires: `billing:partner_subscription:write` scope - [Get subscription by token](https://x-series-api.lightspeedhq.com/reference/partnertokenget.md): Returns a subscription token data 🔒 Requires: `billing:partner_subscription:read` scope - [Create a partner update subscription token](https://x-series-api.lightspeedhq.com/reference/partnerupdatesubscriptiontoken.md): Creates a partner subscription token with the intention of updating a subscription (called by partner using retailer's access token) 🔒 Requires: `billing:partner_subscription:write` scope - [List payment types](https://x-series-api.lightspeedhq.com/reference/listpaymenttypes.md): Returns a paginated collection of payment types. 🔒 Requires: `payment_types:read` scope - [List price book products](https://x-series-api.lightspeedhq.com/reference/listpricebookproducts.md): Returns a paginated list of price book products. 🔒 Requires: `products:read:price_books` scope - [List price books](https://x-series-api.lightspeedhq.com/reference/listpricebooksv3.md): Returns a paginated list of price books. 🔒 Requires: `products:read:price_books` `customers:read` `outlets:read` scopes - [Create a single price book](https://x-series-api.lightspeedhq.com/reference/createpricebookv3.md): Create a price book 🔒 Requires: `products:write:price_books` `customers:read` scopes - [Get a single price book](https://x-series-api.lightspeedhq.com/reference/getpricebookbyidv3.md): Returns a single price book with a requested ID 🔒 Requires: `products:read:price_books` `customers:read` `outlets:read` scopes - [Update a single price book](https://x-series-api.lightspeedhq.com/reference/updatepricebookv3.md): Update a price book by ID 🔒 Requires: `products:write:price_books` `customers:read` scopes - [Delete some entries for a price book](https://x-series-api.lightspeedhq.com/reference/deletepricebookproducts.md): Delete price book product entries. > **Note**: You may not delete more than 100 price book products at a time. > **Note**: The request body params can be used within request headers. Header key name is `data` 🔒 Requires: `products:write:price_books` scope - [List price book products per price book](https://x-series-api.lightspeedhq.com/reference/getpricebookproductsforpricebook.md): Returns a list of price book products for a given price book. > **Note**: The returned retail price is the tax exclusive price of the product. 🔒 Requires: `products:read:price_books` scope - [Update the products in a price book](https://x-series-api.lightspeedhq.com/reference/updatepricebookproducts.md): Update price book products. > **Note**: When adding a product the retail price is the tax exclusive price of the product if your store is tax exclusive, and tax inclusive if your store is tax inclusive. The returned value is always tax exclusive. > **Note**: The request body may not contain more than 100 price book products. 🔒 Requires: `products:write:price_books` `products:read` scopes - [Add the products to a price book](https://x-series-api.lightspeedhq.com/reference/addpricebookproducts.md): Create price book products. > **Note**: When adding a product the retail price is the tax exclusive price of the product if your store is tax exclusive, and tax inclusive if your store is tax inclusive. The returned value is always tax exclusive. > **Note**: The request body may not contain more than 100 price book products. 🔒 Requires: `products:write:price_books` `products:read` scopes - [Update the products in a price book](https://x-series-api.lightspeedhq.com/reference/updatepricebookproductswithputop.md): Update price book products. > **Note**: When adding a product the retail price is the tax exclusive price of the product if your store is tax exclusive, and tax inclusive if your store is tax inclusive. The returned value is always tax exclusive. > **Note**: The request body may not contain more than 100 price book products. 🔒 Requires: `products:write:price_books` `products:read` scopes - [List product categories](https://x-series-api.lightspeedhq.com/reference/listproductcategories.md): 🔒 Requires: `products:read` scope - [Delete a list of product categories](https://x-series-api.lightspeedhq.com/reference/deleteproductcategories.md): Delete a list of categories. If the category is a parent or root, the descendent categories also get deleted. Products associated to the deleted category are assigned to the parent, or if the deleted category is a root, the products are unassigned. 🔒 Requires: `products:write` scope - [Create and update a product category hierarchy](https://x-series-api.lightspeedhq.com/reference/createupdateproductcategories.md): 🔒 Requires: `products:write` scope - [Delete a product image](https://x-series-api.lightspeedhq.com/reference/deleteproductimagebyid.md): Deletes the product image with the requested ID. 🔒 Requires: `products:write` scope - [Get a single product image data](https://x-series-api.lightspeedhq.com/reference/getproductimagedatabyid.md): Returns the metadata for a single product image with a given ID. This method is useful for checking the status of an image after it was uploaded. 🔒 Requires: `products:read` scope - [Set image position](https://x-series-api.lightspeedhq.com/reference/setimageposition.md): Allows for changing the image position in the list 🔒 Requires: `products:write` scope - [List product types](https://x-series-api.lightspeedhq.com/reference/listproducttypes.md): **DEPRECATED** We recommend using the product_categories endpoint instead. Returns a paginated list of product types. 🔒 Requires: `products:read` scope - [Get a single product type](https://x-series-api.lightspeedhq.com/reference/getproducttypebyid.md): Returns a single product type with a given ID. 🔒 Requires: `products:read` scope - [List products](https://x-series-api.lightspeedhq.com/reference/listproducts.md): Returns a paginated list of products. To search for products, please have a look at our [Search endpoint](/reference/search-1) on what is supported. 🔒 Requires: `products:read` scope - [Create product](https://x-series-api.lightspeedhq.com/reference/createproduct.md): Creates a new product. 🔒 Requires: `products:write` scope - [Delete a single product](https://x-series-api.lightspeedhq.com/reference/deleteproduct.md): Deletes a single product. If a variant ID is provided, that single variant is removed. 🔒 Requires: `products:write` scope - [Get a single product](https://x-series-api.lightspeedhq.com/reference/getproductbyid.md): Returns a single product object with a given ID. 🔒 Requires: `products:read` scope - [Update a product](https://x-series-api.lightspeedhq.com/reference/updateproduct.md): Update an existing product. 🔒 Requires: `products:write` scope - [Upload an image](https://x-series-api.lightspeedhq.com/reference/uploadimage.md): Upload a binary file with an image to be used for a product. This request should be encoded as `multipart/form-data`. > **Please Note** If you are reading this on https://x-series-api.lightspeedhq.com then the `Try It!` generated code will not work as the underlying code generator assumes the image will be base64 encoded, which the API does not support. Please have a look at https://x-series-api.lightspeedhq.com/docs/products_image_upload_basics instead. 🔒 Requires: `products:write` scope - [Delete a product family](https://x-series-api.lightspeedhq.com/reference/deleteproductfamily.md): Deletes a product family. The /all suffix is provided to delete an entire variant family. 🔒 Requires: `products:write` scope - [Get a list of price books the given product is in](https://x-series-api.lightspeedhq.com/reference/getpricebooksforproduct.md): This endpoint returns the list of price books the given product is in. 🔒 Requires: `products:read:price_books` scope - [Apply discounts to a sale object](https://x-series-api.lightspeedhq.com/reference/applydiscount.md): This will find the best possible promotion to a sale, apply it and return the sale and the discount. * Despite its `POST` method, this endpoint does not modify any server-side state. * It is the caller's responsibility to pass along the full details of the sale, including all customer information and product information (product type, tags, etc.). 🔒 Requires: `promotions:read` `outlets:read` scopes - [List promotions](https://x-series-api.lightspeedhq.com/reference/listpromotions.md): This endpoint lists all promotions for a retailer. There are optional query parameters that allow filtering promotions. They can't be combined: - `end_time_from` - only show promotions that have end\_time after or equal to this time - `end_time_to` - only show promotions that have end\_time before this time For example. the time format for end\_time\_from and end\_time\_to are: `2047-06-21T13:00:00` 🔒 Requires: `promotions:read` scope - [Create a promotion](https://x-series-api.lightspeedhq.com/reference/createpromotion.md): This endpoint creates a new promotion. It responds with the newly-created promotion, including the promotion's ID. 🔒 Requires: `promotions:write` scope - [Search promotions](https://x-series-api.lightspeedhq.com/reference/searchpromotions.md): This endpoint can be used to find promotions matching specific criteria. 🔒 Requires: `promotions:read` scope - [Get a promotion by ID](https://x-series-api.lightspeedhq.com/reference/getpromotionbyid.md): This will retrieve a single promotion using the given ID. 🔒 Requires: `promotions:read` scope - [Update a promotion](https://x-series-api.lightspeedhq.com/reference/updatepromotion.md): This endpoint updates an existing promotion by ID. * All of a promotion's fields except its id may be updated. * There are no partial updates. * All fields must be specified in the update. * The response contains the updated promotion object. 🔒 Requires: `promotions:write` scope - [Get products for a promotion](https://x-series-api.lightspeedhq.com/reference/getpromotionproducts.md): Get a list of products applicable for this promotion, and their discount price. It takes in `page_size`, `offset` and `name` (use for searching product by product name) as query parameters. The endpoint returns: * a list of products with discount for the condition product set, and * another list for the action product sets. 🔒 Requires: `promotions:read` `products:read` scopes - [Get the promo codes for a promotion](https://x-series-api.lightspeedhq.com/reference/getpromotionpromocodes.md): Get the promo codes associated with this promotion. 🔒 Requires: `promotions:read` scope - [List Quotes](https://x-series-api.lightspeedhq.com/reference/get-quotes.md): Returns a paginated list of quotes. 🔒 Requires: `sales:read` scope - [Get Quote](https://x-series-api.lightspeedhq.com/reference/get-quote-quote_id.md): Returns a single quote with a given ID. 🔒 Requires: `sales:read` scope - [List button layouts](https://x-series-api.lightspeedhq.com/reference/listbuttonlayouts.md): Returns a versioned collection of button layouts for the authenticated retailer. Button layouts define the arrangement of quick key buttons on a register. 🔒 Requires: `registers:read` scope - [Get a single button layout](https://x-series-api.lightspeedhq.com/reference/getbuttonlayoutbyid.md): Returns a single button layout by id. Button layouts define the arrangement of quick key buttons on a register. 🔒 Requires: `registers:read` scope - [List registers](https://x-series-api.lightspeedhq.com/reference/listregisters.md): Returns a paginated list of registers. 🔒 Requires: `registers:read` scope - [Get a single register](https://x-series-api.lightspeedhq.com/reference/getregisterbyid.md): Returns a single register with the requested ID. 🔒 Requires: `registers:read` scope - [Close a single register](https://x-series-api.lightspeedhq.com/reference/closeregister.md): Closes a single register with the requested ID. 🔒 Requires: `register:close` `payment_types:read` scopes - [Open a single register](https://x-series-api.lightspeedhq.com/reference/openregister.md): Opens a single register with the requested ID. 🔒 Requires: `register:open` scope - [Get all the payments data associated with a single register.](https://x-series-api.lightspeedhq.com/reference/registerpaymentssummary.md): Returns a payload containing payment totals for all payments types defined in the account for a single register. 🔒 Requires: `payments:read` scope - [Get information about this retailer](https://x-series-api.lightspeedhq.com/reference/getretailer.md): This endpoint returns information about the retailer. 🔒 Requires: `retailer:read` `payment_types:read` scopes - [List Sales](https://x-series-api.lightspeedhq.com/reference/listsales.md): Returns a paginated list of sales. To search for sales, please have a look at our [Search endpoint](/reference/search-1) on what is supported. 🔒 Requires: `sales:read` scope - [Create a sale](https://x-series-api.lightspeedhq.com/reference/createsale.md): Create a sale. Returns the ID of the created sale. See [Sales 101](/docs/sales_101) for usage information. Migrating from `v0.9`? See the [migration guide](/docs/sales_migration_guide). 🔒 Requires: `sales:write` scope - [Get a single sale](https://x-series-api.lightspeedhq.com/reference/getsalebyid.md): Returns a single sale with a given ID. 🔒 Requires: `sales:read` scope - [Update a sale](https://x-series-api.lightspeedhq.com/reference/updatesale.md): Update an existing sale by ID. 🔒 Requires: `sales:write` scope - [Return a sale](https://x-series-api.lightspeedhq.com/reference/initreturnsale.md): Initializes a return for an existing closed sale and returns the newly created SAVED return sale. Use this endpoint to start the return workflow before adding refund payments or finalizing the returned items. See [the tutorial](/docs/sales_returns) for more information. 🔒 Requires: `sales:write` `users:read` scopes - [Search for resources](https://x-series-api.lightspeedhq.com/reference/search-1.md): This endpoint allows integrators to search all of the most commonly used resources, **sales**, **products** and **customers**. Each type allowing search by a number of different parameters. ### Supported resource types and attributes - **Sales** - date_from - date_to - time_from - time_to - timezone - status - state - attributes - invoice_number - customer_id - user_id - outlet_id - register_id - payment_type_id - product_id - sale_total - customer_name - **Products** - sku **_(values must be lowercased)_** - supplier_id - brand_id - tag_id - product_type_id - variant_parent_id - **Customers** - customer_code - first_name - last_name - company_name - mobile - phone - email ### Sorting and pagination Unlike other endpoints, search results from this endpoint can be sorted by any of the attributes above. Because of that, the default [pagination](https://x-series-api.lightspeedhq.com/docs/pagination#api-20) mechanism is not appropriate for this endpoint. Instead, this endpoint uses `offset` and `page_size` attributes to handle search results spanning multiple pages. 🔒 Requires one of the following: - `sales:read` scope when searching for sales - `products:read` scope when searching for products - `customers:read` scope when searching for customers - [List serial numbers](https://x-series-api.lightspeedhq.com/reference/get-serialnumbers.md): Returns a paginated list of serial numbers. 🔒 Requires: `serial_numbers:read` scope - [Create a serial number](https://x-series-api.lightspeedhq.com/reference/create-serialnumber.md): Creates a serial number. 🔒 Requires: `serial_numbers:write` scope - [Delete a serial number](https://x-series-api.lightspeedhq.com/reference/delete-serialnumber.md): Deletes a serial number. 🔒 Requires: `serial_numbers:write` scope - [Get a single serial number](https://x-series-api.lightspeedhq.com/reference/get-serialnumber.md): Returns a single serial number. 🔒 Requires: `serial_numbers:read` scope - [List a customer's service items](https://x-series-api.lightspeedhq.com/reference/listserviceitems.md): Returns a paginated list of customer's service items. 🔒 Requires: `services:read` scope - [List service statuses](https://x-series-api.lightspeedhq.com/reference/listservicestatuses.md): Returns all service statuses for the retailer, including system defaults and custom ones. **Only available with the Service Orders module enabled.** 🔒 Requires: `services:read` scope - [Create a service status](https://x-series-api.lightspeedhq.com/reference/createservicestatus.md): Creates a new custom service status for the retailer. The new status is appended at the end of the display order. Use the PATCH endpoint to change its position after creation. **Only available with the Service Orders module enabled.** 🔒 Requires: `services:write` scope - [Delete a service status](https://x-series-api.lightspeedhq.com/reference/deleteservicestatus.md): Deletes a custom service status. System default statuses cannot be deleted. A status cannot be deleted if it is still assigned to one or more service orders. **Only available with the Service Orders module enabled.** 🔒 Requires: `services:write` scope - [Get a service status](https://x-series-api.lightspeedhq.com/reference/getservicestatus.md): Returns a single service status by ID. **Only available with the Service Orders module enabled.** 🔒 Requires: `services:read` scope - [Update a service status](https://x-series-api.lightspeedhq.com/reference/updateservicestatus.md): Partially updates a custom service status. Only provided fields are updated. System default statuses cannot be modified. **Only available with the Service Orders module enabled.** 🔒 Requires: `services:write` scope - [List services](https://x-series-api.lightspeedhq.com/reference/listservices.md): Returns a paginated list of services. 🔒 Requires: `services:read` scope - [Create a service order](https://x-series-api.lightspeedhq.com/reference/createservice.md): **Only available with the Service Orders module enabled.** Creates a new service order. This endpoint allows you to create service orders with a customer, a service item, note and location. 🔒 Requires: `services:write` `sales:write` scopes - [Get service](https://x-series-api.lightspeedhq.com/reference/getservice.md): Get a single service order. 🔒 Requires: `services:read` scope - [Get services agenda by outlet](https://x-series-api.lightspeedhq.com/reference/get-agenda-outlet_id.md): Returns the service agenda for the specified outlet within the given time window. 🔒 Requires: `services:read` scope - [Get store credit usage for the store](https://x-series-api.lightspeedhq.com/reference/liststorecredit.md): Returns all the store credit customers in a store with their store credit balance and a list of last store credit transactions for each customer 🔒 Requires: `store_credits:read` scope - [Bulk Store Credit customers](https://x-series-api.lightspeedhq.com/reference/bulkstorecreditlist.md): Returns all the store credit customers in a store with their store credit balance and a list of last store credit transactions for each customer 🔒 Requires: `store_credits:read` scope - [Store credit report](https://x-series-api.lightspeedhq.com/reference/storecreditreport.md): Returns a report of store credits. 🔒 Requires: `store_credits:read` scope - [Store Credit operations and a balance of a customer](https://x-series-api.lightspeedhq.com/reference/liststorecreditforcustomer.md): Returns a balance and a history of store credit operations for the given customer id. 🔒 Requires: `store_credits:read` scope - [Create a store credit transaction](https://x-series-api.lightspeedhq.com/reference/createstorecredittransaction.md): Creates a new store credit transaction. The type determines what sort of transaction it is. * "REDEMPTION" - Use this type when you want to redeem a certain amount from the store credit balance. The amount MUST be negative. If you want to add an amount to the balance use the "ISSUE" type. 🔒 Requires: `store_credits:write:redeem` * "ISSUE" - Use this type when you issue store credit to a customer. 🔒 Requires: `store_credits:write:issue` * "REVERSE" - Use this type when voiding an earlier ISSUE or REDEMPTION transaction. 🔒 Requires: `store_credits:write:redeem` If the customer account does not have enough credit to honour a REDEMPTION transaction a 422 HTTP status code will be returned. ## Idempotency Please populate the client_id field with a unique transaction identifier, to ensure that the transaction is safe from double-submit problems. When creating an REVERSE operation, client_id must be equal to client_id of a reversed operation. See [the tutorial](/docs/store_credit#idempotency) for more information. - [Bulk Store Credit customers balances](https://x-series-api.lightspeedhq.com/reference/bulkbalancesstorecreditlist.md): Returns all the store credit customers in a store with their store credit balance. 🔒 Requires: `store_credits:read` scope - [Store Credit balance of a customer](https://x-series-api.lightspeedhq.com/reference/storecreditbalanceforcustomer.md): Returns a balance for the given customer id. 🔒 Requires: `store_credits:read` scope - [Create a store credit HOLD transaction](https://x-series-api.lightspeedhq.com/reference/createstorecredithold.md): Creates a tranaction that represents temporary store credit redemption That redemption should be reverted later AND may get followed by a REDEMPTION - [Reverse a store credit HOLD transaction](https://x-series-api.lightspeedhq.com/reference/reversestorecredithold.md): Creates a tranaction reverting a HOLD operation - [List suppliers](https://x-series-api.lightspeedhq.com/reference/listsuppliers.md): Returns a paginated list of suppliers. 🔒 Requires: `suppliers:read` scope - [Create new supplier](https://x-series-api.lightspeedhq.com/reference/createsupplier.md): Creates a new supplier. 🔒 Requires: `suppliers:write` scope - [Delete a single supplier](https://x-series-api.lightspeedhq.com/reference/deletesupplierbyid.md): Deletes a supplier. If there are products associated with the supplier, the products will be disassociated from the supplier. 🔒 Requires: `suppliers:write` scope - [Get a single supplier](https://x-series-api.lightspeedhq.com/reference/getsupplierbyid.md): Returns a single supplier with a given ID. 🔒 Requires: `suppliers:read` scope - [Update a supplier](https://x-series-api.lightspeedhq.com/reference/updatesupplierbyid.md): Updates a supplier. 🔒 Requires: `suppliers:write` scope - [List tags](https://x-series-api.lightspeedhq.com/reference/listtags.md): Returns a collection of tags. 🔒 Requires: `products:read` scope - [Create tag](https://x-series-api.lightspeedhq.com/reference/createtag.md): Creates a new tag. 🔒 Requires: `products:write` scope - [Delete a single tag](https://x-series-api.lightspeedhq.com/reference/deletetagbyid.md): Deletes a tag. If there are products associated with the tag, the products will be disassociated from the tag. 🔒 Requires: `products:write` scope - [Get a single tag](https://x-series-api.lightspeedhq.com/reference/gettagbyid.md): Returns a single tag with a given ID. 🔒 Requires: `products:read` scope - [Update a single tag](https://x-series-api.lightspeedhq.com/reference/updatetagbyid.md): Updates a tag. 🔒 Requires: `products:write` scope - [List taxes](https://x-series-api.lightspeedhq.com/reference/listtaxes.md): Returns a paginated list of taxes. 🔒 Requires: `taxes:read` scope - [Create tax](https://x-series-api.lightspeedhq.com/reference/createtax.md): Creates a new tax. 🔒 Requires: `taxes:write` scope - [Get a single tax](https://x-series-api.lightspeedhq.com/reference/gettaxbyid.md): Returns a single tax with a given ID. 🔒 Requires: `taxes:read` scope - [Get current user](https://x-series-api.lightspeedhq.com/reference/getuser.md): Returns the current user. 🔒 Requires: `users:read` scope - [List users](https://x-series-api.lightspeedhq.com/reference/listusers.md): Returns a paginated list of users. 🔒 Requires: `users:read` scope - [Get multiple users by id](https://x-series-api.lightspeedhq.com/reference/getusersbyid.md): Get multiple users by id. 🔒 Requires: `users:read` scope - [Delete a single user](https://x-series-api.lightspeedhq.com/reference/deleteuserbyid.md): Returns the user that has been deleted. - [Get a single user](https://x-series-api.lightspeedhq.com/reference/getuserbyid.md): Returns a single user with the requested ID. 🔒 Requires: `users:read` scope - [Get the sales totals for a single user](https://x-series-api.lightspeedhq.com/reference/getsalestotalsforuserbyid.md): Returns a single user's sales totals. - [Delete user sessions](https://x-series-api.lightspeedhq.com/reference/deletesessionsbyuserid.md): Deletes all sessions and personal tokens of the given user. 🔒 Requires: `users:write` scope - [List webhooks](https://x-series-api.lightspeedhq.com/reference/get-webhooks.md): List all webhooks. 🔒 Requires: `webhooks` scope - [Create Webhook](https://x-series-api.lightspeedhq.com/reference/post-webhooks.md): Create a webhook. 🔒 Requires: `webhooks` scope - [Delete Webhook](https://x-series-api.lightspeedhq.com/reference/delete-webhooks-webhookid.md): Delete a webhook 🔒 Requires: `webhooks` scope - [Get Webhook](https://x-series-api.lightspeedhq.com/reference/get-webhooks-id.md): Fetch a single webhook by its ID. 🔒 Requires: `webhooks` scope - [Update Webhook](https://x-series-api.lightspeedhq.com/reference/put-webhooks-id.md): Update an existing webhook 🔒 Requires: `webhooks` scope - [List custom field definitions](https://x-series-api.lightspeedhq.com/reference/getcustomfields.md): Returns the custom field definitions for a given entity type. 🔒 Requires: `custom_fields:read` scope - [Define a new custom field](https://x-series-api.lightspeedhq.com/reference/createcustomfield.md): Create a new custom field definition for a given entity type. 🔒 Requires: `custom_fields:write` scope - [List custom field values](https://x-series-api.lightspeedhq.com/reference/getcustomfieldvalues.md): Returns the custom field values for a given entity. 🔒 Requires: `custom_fields:read` scope - [Set new custom field values](https://x-series-api.lightspeedhq.com/reference/setcustomfieldvalues.md): Set new custom field values on a given entity. 🔒 Requires: `custom_fields:write` scope - [Delete a custom field](https://x-series-api.lightspeedhq.com/reference/delete-custom-field.md): Delete a custom field and all the values stored on that field. 🔒 Requires: `custom_fields:write` scope - [Update a custom field](https://x-series-api.lightspeedhq.com/reference/update-custom-field.md): Updates properties on a custom field. 🔒 Requires: `custom_fields:write` scope - [List remote rules](https://x-series-api.lightspeedhq.com/reference/get-remote-rules.md): Returns the remote business rules registered on the retailer. 🔒 Requires: `remote_rules:read` scope - [Create remote rule](https://x-series-api.lightspeedhq.com/reference/create-remote-rule.md): Register a new remote rule for the retailer. 🔒 Requires: `remote_rules:write` scope - [Delete a remote rule](https://x-series-api.lightspeedhq.com/reference/delete-remote-rule.md): Delete a remote business rule. 🔒 Requires: `remote_rules:write` scope - [List rules](https://x-series-api.lightspeedhq.com/reference/get-rules.md): Returns the business rules for the retailer. 🔒 Requires: `business_rules:read` scope - [Create rule](https://x-series-api.lightspeedhq.com/reference/create-rule.md): Create a rule for the retailer. 🔒 Requires: `business_rules:write` scope - [Delete a business rule](https://x-series-api.lightspeedhq.com/reference/delete-rule.md): Delete a business rule. 🔒 Requires: `business_rules:write` scope - [Perform a Loyalty Adjustment bulk operation](https://x-series-api.lightspeedhq.com/reference/post_loyalty-adjustments-bulk.md): Performs an operation which updates loyalty balance for multiple customers Requires the `loyalty.transaction.write` permission. - [Delete promo codes](https://x-series-api.lightspeedhq.com/reference/deletepromocodesbulk.md): Delete promo codes, by promocode IDs 🔒 Requires: `promotions:write` scope - [Get the active status of promo codes](https://x-series-api.lightspeedhq.com/reference/getactivepromocodesbulk.md): Get promo codes, with their associated promotions. 🔒 Requires: `promotions:read` scope - [List shifts](https://x-series-api.lightspeedhq.com/reference/listshifts.md): Returns a paginated list of shifts. - [Retrieve all Variant Attributes](https://x-series-api.lightspeedhq.com/reference/listvariantattributes.md): Retrieve all Variant Attributes. 🔒 Requires: `products:read` scope - [Create a Variant Attribute](https://x-series-api.lightspeedhq.com/reference/createvariantattribute.md): Variant Attributes are required when creating variants. They are used to specify what properties make a particular SKU different to another. e.g. You may have an attribute 'Size' that lets you differentiate variants based on their size. 🔒 Requires: `products:write` scope - [Delete a variant attribute](https://x-series-api.lightspeedhq.com/reference/deletevariantattribute.md): Note you can't delete a variant attribute that is currently being used by a family. 🔒 Requires: `products:write` scope - [Retrieve a single Variant Attribute](https://x-series-api.lightspeedhq.com/reference/getvariantattributes.md): Retrieves a single Variant Attribute with the given id. 🔒 Requires: `products:read` scope - [Update a Variant Attribute's](https://x-series-api.lightspeedhq.com/reference/updatevariantattribute.md): Updates a Variant Attribute's name. 🔒 Requires: `products:write` scope ## Changelog - [2026-07 Voiding of other parked returns](https://x-series-api.lightspeedhq.com/changelog/2026-07-void-other-parked-returns.md) - [2026-07 Prevent mixing of referenced and unreferenced returns](https://x-series-api.lightspeedhq.com/changelog/2026-07-prevent-mixing-of-referenced-and-unreferenced-returns.md) - [2026-07 Strict Postal Code Validation (40 Countries)](https://x-series-api.lightspeedhq.com/changelog/2026-07-extended-postal-code-validation.md) - [2026-01 Return Sale Endpoint Method Update](https://x-series-api.lightspeedhq.com/changelog/2026-06-return-sale-post-date-versioned-apis.md) - [2026-05 New Sales Search Filters and Sorting](https://x-series-api.lightspeedhq.com/changelog/2026-05-new-sales-search-filters.md) - [2026-04 Inventory Levels Reorder Method](https://x-series-api.lightspeedhq.com/changelog/2026-05-inventory-levels-reorder-method.md) - [2026-04 Deprecation of Sale Fulfillment Endpoints](https://x-series-api.lightspeedhq.com/changelog/2026-05-deprecate-sale-fulfillment-endpoints.md) - [2026-01 Adjustment APIs](https://x-series-api.lightspeedhq.com/changelog/2026-05-adjustment-apis-2026-01.md) - [2026-04 Reorder Points Support](https://x-series-api.lightspeedhq.com/changelog/2026-05-reorder-points-2026-04.md) - [2026-04 Gift Card & Transaction Endpoints](https://x-series-api.lightspeedhq.com/changelog/2026-03-new-gift-card-endpoints-2026-04.md)