Lightspeed Commerce Products API

openapi: 3.2.0
info:
  contact:
    email: x-series.api@lightspeedhq.com
    name: Lightspeed Developer Relations
    url: https://developers.retail.lightspeed.app
  description: Lightspeed Retail (X-Series) API.
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  termsOfService: https://developers.lightspeedhq.com/terms
  title: 2026-07 Products API
  version: 2026-07
servers:
- url: https://{domain_prefix}.retail.lightspeed.app/api/2026-07
  variables:
    domain_prefix:
      default: example
      description: Domain prefix of the store to be operated on
security:
- bearerAuth: []
tags:
- description: Product operations
  name: Products
paths:
  /products:
    get:
      description: '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'
      operationId: ListProducts
      parameters:
      - description: The lower limit for the version numbers to be included in the response.
        in: query
        name: after
        schema:
          format: int64
          type: integer
      - description: The upper limit for the version numbers to be included in the response.
        in: query
        name: before
        schema:
          format: int64
          type: integer
      - description: Indicates whether deleted items should be included in the response.
        in: query
        name: deleted
        schema:
          type: boolean
      - description: The maximum number of items to be returned in the response.
        in: query
        name: page_size
        schema:
          type: integer
      - description: Allows loading a product by one of its SKUs. Note that all other query params are ignored if this is provided.
        in: query
        name: sku
        schema:
          type: string
      - description: Allows loading products with the name provided in this parameter. This query typically retrieves all products from the product family with the provided name. Note that all other query parameters are ignored if this is provided.
        in: query
        name: name
        schema:
          type: string
      - description: Alias for 'name'. Allows loading products that belong to the family with the name provided in this parameter. Note that all other query parameters are ignored if this is provided.
        in: query
        name: family_name
        schema:
          type: string
      - description: Side-load related entities. Supported value 'composite_products'.
        explode: true
        in: query
        name: includes[]
        schema:
          items:
            type: string
          type: array
        style: form
      - description: Whether to include product image fields in the response. Defaults to true.
        in: query
        name: include_images
        schema:
          type: boolean
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                - active: true
                  attributes: []
                  brand: {}
                  button_order: 0
                  categories: []
                  created_at: '2015-01-08T20:41:50+00:00'
                  handle: '0003'
                  has_inventory: true
                  has_variants: false
                  id: b8ca3a65-0183-11e4-fbb5-9776c5cd0240
                  image_thumbnail_url: https://secure.retail.lightspeed.app/images/placeholder/product/no-image-white-thumb.png
                  image_url: https://secure.retail.lightspeed.app/images/placeholder/product/no-image-white-standard.png
                  images: []
                  is_active: true
                  is_composite: false
                  name: Product 0003
                  price_excluding_tax: 2.63158
                  price_including_tax: 3.02632
                  sku: '0003'
                  source: USER
                  supplier: {}
                  supply_price: 0
                  tag_ids: []
                  type: {}
                  updated_at: '2015-08-18T23:28:00+00:00'
                  variant_name: Product 0003
                  variant_options: []
                  version: 59780745
                - active: true
                  attributes: []
                  brand: {}
                  button_order: 0
                  categories: []
                  created_at: '2015-01-08T20:41:51+00:00'
                  handle: '0005'
                  has_inventory: true
                  has_variants: false
                  id: b8ca3a65-0183-11e4-fbb5-9776c5faaed2
                  image_thumbnail_url: https://secure.retail.lightspeed.app/images/placeholder/product/no-image-white-thumb.png
                  image_url: https://secure.retail.lightspeed.app/images/placeholder/product/no-image-white-standard.png
                  images: []
                  is_active: true
                  is_composite: false
                  name: Product 0005
                  price_excluding_tax: 4.38596
                  price_including_tax: 5.04385
                  sku: '0005'
                  source: USER
                  supplier: {}
                  supply_price: 0
                  tag_ids: []
                  type: {}
                  updated_at: '2015-08-18T23:28:00+00:00'
                  variant_name: Product 0005
                  variant_options: []
                  version: 59780753
                - active: true
                  attributes: []
                  brand: {}
                  button_order: 0
                  categories: []
                  composite_bom:
                    b8ca3a65-0183-11e4-fbb5-9776c611d865: 2
                    d796d8b2-ff79-48fa-8e6e-a15e2e0bd429: 3
                  created_at: '2015-01-08T20:41:51+00:00'
                  handle: '0006'
                  has_inventory: true
                  has_variants: false
                  id: b8ca3a65-0183-11e4-fbb5-9776c611d865
                  image_thumbnail_url: https://secure.retail.lightspeed.app/images/placeholder/product/no-image-white-thumb.png
                  image_url: https://secure.retail.lightspeed.app/images/placeholder/product/no-image-white-standard.png
                  images: []
                  is_active: true
                  is_composite: false
                  name: Product 0006
                  price_excluding_tax: 5.26316
                  price_including_tax: 6.05263
                  product_codes:
                  - code: '123456'
                    type: custom
                  product_suppliers:
                  - code: code
                    id: cfbf30bd-4b6a-47df-931c-1a326acc1769
                    price: 19
                    product_id: d796d8b2-ff79-48fa-8e6e-a15e2e0bd429
                    supplier_id: 63c4c033-3019-4582-99e7-446baacca1b0
                    supplier_name: supplier_1
                  sku: '0006'
                  source: USER
                  supplier: {}
                  supply_price: 0
                  tag_ids: []
                  type: {}
                  updated_at: '2015-08-18T23:28:00+00:00'
                  variant_name: Product 0006
                  variant_options: []
                  version: 59780757
                version:
                  max: 59780757
                  min: 59780745
              schema:
                $ref: '#/components/schemas/ProductCollection'
          description: ''
      summary: List products
      tags:
      - Products
    post:
      description: 'Creates a new product.


        🔒 Requires: `products:write` scope'
      operationId: CreateProduct
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProductCreateBody'
        description: '**Note**: You cannot include both `price_including_tax` and `price_excluding_tax`.'
        required: true
      responses:
        '200':
          content:
            Example:
              example:
                data:
                - 0717b8d6-a4eb-858b-351d-16274fdf186c
            application/json:
              schema:
                properties:
                  data:
                    description: An array containing the ID or IDs of the new products.
                    items:
                      type: string
                    type: array
                type: object
          description: OK
      summary: Create product
      tags:
      - Products
  /products/{product_id}:
    delete:
      description: 'Deletes a single product. If a variant ID is provided, that single variant is removed.


        🔒 Requires: `products:write` scope'
      operationId: DeleteProduct
      parameters:
      - description: The product id
        in: path
        name: product_id
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
      summary: Delete a single product
      tags:
      - Products
    get:
      description: 'Returns a single product object with a given ID.


        🔒 Requires: `products:read` scope'
      operationId: GetProductByID
      parameters:
      - description: The product id
        in: path
        name: product_id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  active: true
                  attributes: []
                  brand:
                    id: 0adaafb3-6583-11e5-fb60-d5b67a17df2f
                    name: Peak Performance
                    version: 882391722
                  brand_id: 0adaafb3-6583-11e5-fb60-d5b67a17df2f
                  button_order: 2
                  categories:
                  - id: b8ca3a65-0183-11e4-fbb5-a7e973b74d92
                    name: tag_test
                    version: 1446856
                  - id: bc305bf6-6183-11e4-f15a-16ced23b8465
                    name: variant
                    version: 961180
                  created_at: '2014-12-01T18:34:15+00:00'
                  description: <p>The best product ever, except for the next one.</p>
                  handle: bravo
                  has_inventory: true
                  has_variants: true
                  id: b8ca3a65-0183-11e4-fbb5-7988a6ed80f8
                  image_thumbnail_url: https://vendimageuploadcdn.global.ssl.fastly.net/160,fit,q90/vend-images/product/original/f/0/f0ebadbc30947444d438678a4a7bd6d996f392fc.jpg
                  image_url: https://vendimageuploadcdn.global.ssl.fastly.net/350,fit,q90/vend-images/product/original/f/0/f0ebadbc30947444d438678a4a7bd6d996f392fc.jpg
                  images:
                  - id: 06bf537b-c783-11e6-f6b9-b73917d393b6
                    sizes:
                      original: https://vendimageuploadcdn.global.ssl.fastly.net/1920,fit/vend-images/product/original/f/0/f0ebadbc30947444d438678a4a7bd6d996f392fc.jpg
                      sl: https://vendimageuploadcdn.global.ssl.fastly.net/150x150,q90/vend-images/product/original/f/0/f0ebadbc30947444d438678a4a7bd6d996f392fc.jpg
                      sm: https://vendimageuploadcdn.global.ssl.fastly.net/100x100,q90/vend-images/product/original/f/0/f0ebadbc30947444d438678a4a7bd6d996f392fc.jpg
                      ss: https://vendimageuploadcdn.global.ssl.fastly.net/50x50,q90/vend-images/product/original/f/0/f0ebadbc30947444d438678a4a7bd6d996f392fc.jpg
                      st: https://vendimageuploadcdn.global.ssl.fastly.net/40x40,q90/vend-images/product/original/f/0/f0ebadbc30947444d438678a4a7bd6d996f392fc.jpg
                      standard: https://vendimageuploadcdn.global.ssl.fastly.net/350,fit,q90/vend-images/product/original/f/0/f0ebadbc30947444d438678a4a7bd6d996f392fc.jpg
                      thumb: https://vendimageuploadcdn.global.ssl.fastly.net/160,fit,q90/vend-images/product/original/f/0/f0ebadbc30947444d438678a4a7bd6d996f392fc.jpg
                    url: https://vendimageuploadcdn.global.ssl.fastly.net/1920,fit/vend-images/product/original/f/0/f0ebadbc30947444d438678a4a7bd6d996f392fc.jpg
                    version: 2398861114
                  is_active: true
                  is_composite: false
                  name: Bravo
                  price_excluding_tax: 110
                  price_including_tax: 126.5
                  product_codes:
                  - code: '123456'
                    type: custom
                  product_suppliers:
                  - code: code
                    id: cfbf30bd-4b6a-47df-931c-1a326acc1769
                    price: 19
                    product_id: d796d8b2-ff79-48fa-8e6e-a15e2e0bd429
                    supplier_id: 63c4c033-3019-4582-99e7-446baacca1b0
                    supplier_name: supplier_1
                  product_type_id: b1e2babe-f019-11e3-a0f5-b8ca3a64f8f4
                  sku: '787878'
                  source: USER
                  supplier:
                    description: ''
                    id: dc85058a-a683-11e5-ef46-08f9a926615e
                    name: Peak
                    source: ''
                    version: 2089502
                  supplier_code: '123456'
                  supplier_id: dc85058a-a683-11e5-ef46-08f9a926615e
                  supply_price: 100
                  tag_ids:
                  - b8ca3a65-0183-11e4-fbb5-a7e973b74d92
                  - bc305bf6-6183-11e4-f15a-16ced23b8465
                  type:
                    id: b1e2babe-f019-11e3-a0f5-b8ca3a64f8f4
                    name: General
                    version: 449902
                  updated_at: '2017-08-21T23:50:39+00:00'
                  variant_name: Bravo / Black / Cotton / Cotton
                  variant_options:
                  - id: 9a972fbe-3b53-102e-b60f-4abbcbc88955
                    name: Color
                    value: Black
                  - id: 6b8f11e2-5188-11e0-9d7a-4040f540b50a
                    name: Fabric
                    value: Cotton
                  - id: 6b8f11e2-5188-11e0-9d7a-4040f540b50a
                    name: Fabric
                    value: Cotton
                  version: 4284638488
              schema:
                $ref: '#/components/schemas/ProductResponse'
          description: ''
      summary: Get a single product
      tags:
      - Products
    put:
      description: 'Update an existing product.


        🔒 Requires: `products:write` scope'
      operationId: UpdateProduct
      parameters:
      - description: The object identifier of the Product to update.
        in: path
        name: product_id
        required: true
        schema:
          format: uuid
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProductUpdate21Request'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
          description: The response if the API call is successful.
        '404':
          content:
            application/json:
              schema:
                type: object
          description: The response if the product you are attempting to update doesn't exist.
        '422':
          content:
            application/json:
              schema:
                type: object
          description: The response if the update can't be processed.
      summary: Update a product
      tags:
      - Products
  /products/{product_id}/actions/image_upload:
    post:
      description: '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'
      operationId: UploadImage
      parameters:
      - description: The product id
        in: path
        name: product_id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/octet-stream:
            schema:
              description: File to upload. Can be in `jpg` or `png` format.
              format: binary
              properties:
                image:
                  format: binary
                  type: string
              type: object
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImageResponse'
          description: ''
      summary: Upload an image
      tags:
      - Products
  /products/{product_id}/all:
    delete:
      description: 'Deletes a product family. The /all suffix is provided to delete an entire variant family.


        🔒 Requires: `products:write` scope'
      operationId: DeleteProductFamily
      parameters:
      - description: The product id of a family member
        in: path
        name: product_id
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
      summary: Delete a product family
      tags:
      - Products
  /products/{product_id}/price_book_products:
    get:
      description: 'This endpoint returns the list of price books the given product is in.


        🔒 Requires: `products:read:price_books` scope'
      operationId: GetPriceBooksForProduct
      parameters:
      - description: The product id to find in the Price Books
        in: path
        name: product_id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PriceBookProductCollection'
          description: OK
      summary: Get a list of price books the given product is in
      tags:
      - Products
components:
  schemas:
    ProductUpdate21Supplier:
      properties:
        code:
          description: The supplier's code or reference for the product. To remove the code, please provide empty value "".
          type: string
        price:
          description: The cost of supply for the product. -1 price will delete the price.
          type: number
        supplier_id:
          description: The supplier ID.
          type: string
      title: Product Update 2.1 Product Supplier Request
      type: object
    Version:
      description: An object containing the highest and lowest version numbers for all items of the returned collection.
      properties:
        max:
          description: Highest version number of the payload, or `null` when the result set is empty.
          format: int64
          type:
          - integer
          - 'null'
        min:
          description: Lowest version number of the payload, or `null` when the result set is empty.
          format: int64
          type:
          - integer
          - 'null'
      required:
      - max
      - min
      type: object
    ProductCategoryPath:
      properties:
        id:
          description: Object id of the Product Type in the path.
          type: string
        name:
          description: The Product Type name.
          type: string
      required:
      - id
      - name
      title: Product Category Path
      type: object
    PriceBookProductCollection:
      properties:
        data:
          description: An array of Price Book objects wrapped in a top level `data` object.
          items:
            $ref: '#/components/schemas/PriceBookProduct'
          type: array
      required:
      - data
      title: Price Book Product Collection
      type: object
    ProductCollection:
      properties:
        data:
          description: An array of Product objects wrapped in top level `data` object.
          items:
            $ref: '#/components/schemas/Product'
          type: array
        version:
          $ref: '#/components/schemas/Version'
      required:
      - data
      - version
      title: Product Collection
      type: object
    ProductUpdate21Request:
      properties:
        common:
          description: Information to update to the product family. For variants, this will update the fields to all variants in the family.
          properties:
            account_code_purchase:
              description: The code used to attribute the purchase (cost) of the product to a specific account for the Xero integration.
              type: string
            account_code_sale:
              description: The code used to attribute the sales of the product to a specific account for the Xero integration.
              type: string
            brand_id:
              description: The brand ID that the product is associated to. To remove the brand from the product, please provide empty value "".
              type: string
            description:
              description: Product description.
              type: string
            name:
              description: Product name
              type: string
            product_category_id:
              description: 'The product category ID tha the product is associated to. A product can only be associated to the last level (leaf) category.

                To remove the product category from the product, please provide empty value "".

                Product category was previously known as product types.

                '
              type: string
            product_suppliers:
              description: 'A full list of suppliers and its details that are associated to the product family.

                The order of the supplier listed in this list will reflect the supplier''s order in the product.

                The first supplier is the default supplier.

                If do not wish to override the code and price that may be custom per variant, just provide the id.

                '
              items:
                $ref: '#/components/schemas/ProductUpdate21Supplier'
              type: array
            tag_ids:
              description: The full list of tag ids that the product is associated to. To remove all tags, please provide empty list.
              items:
                type: string
              type: array
            track_inventory:
              description: True to enable inventory tracking for product. This will updating of inventory details such as manual adjustments and reorder details.
              type: boolean
            variant_attributes:
              description: 'A full list of the variant attributes for the product family.

                The order of the variant attributes in this list will reflect the order of the attribute on the variant. Maximum three attributes.

                '
              items:
                properties:
                  attribute_id:
                    description: The ID of attribute represented at the specified position in the list.
                    type: string
                type: object
              type: array
          type: object
        details:
          description: Information to update to the product. For variants, this will update the fields for the individual variant product of this request only.
          properties:
            all_outlets_tax:
              description: Set the tax on a product for tax inclusive store.
              properties:
                tax_id:
                  description: The selected custom tax ID. Leave blank ("") to use the default tax.
                  type: string
              type: object
            composite_components:
              description: A full list of composite components.
              items:
                properties:
                  product_id:
                    description: The ID of the component product.
                    format: uuid
                    type: string
                  quantity:
                    description: The quantity of the component product.
                    type: number
                required:
                - product_id
                - quantity
                type: object
              type: array
            dimensions_unit:
              description: The unit for any height, width, or length provided.
              enum:
              - IN
              - CM
              - MM
              - YD
              type: string
            height:
              description: The height of the product. If provided, dimensions_unit for this value must also be provided.
              type: number
            inventory:
              description: A list of inventory outlet information to update.
              items:
                properties:
                  current_amount:
                    description: Current inventory quantity of the product at the given outlet.
                    type: number
                  outlet_id:
                    description: The outlet ID.
                    type: string
                  reorder_amount:
                    description: The default of the quantity for auto-filled inventory orders.
                    type: number
                  reorder_point:
                    description: Quantity below which the product should be included in the auto-filled inventory orders. use -1 to clear the reorder point.
                    type: number
                required:
                - outlet_id
                type: object
              type: array
            is_active:
              description: True to enable Sell on POS, false to disable.
              type: boolean
            length:
              description: The length of the product. If provided, dimensions_unit for this value must also be provided.
              type: number
            loyalty_amount:
              description: The custom loyalty amount. -1 to use the default loyalty amount.
              type: number
            outlet_taxes:
              description: A list of outlet taxes to update on a product for tax exclusive store.
              items:
                properties:
                  outlet_id:
                    description: The outlet ID to apply the tax.
                    type: string
                  tax_id:
                    description: The selected custom tax ID. Leave blank ("") to use the default tax.
                    type: string
                type: object
              type: array
            packaging:
              description: Packaging this product belongs to.
              items:
                properties:
                  amount:
                    type: number
                  destination_product_id:
                    format: uuid
                    type: string
                  source_product_id:
                    format: uuid
                    type: string
                type: object
              type: array
            price_excluding_tax:
              description: Price exclusive of tax. For tax exclusive store.
              type: number
            price_including_tax:
              description: Price inclusive of tax. For tax inclusive store.
              type: number
            product_codes:
              description: A full list of product codes for the product. The first product code is used as the default product code.
              items:
                properties:
                  code:
                    description: The product code value.
                    type: string
                  type:
                    enum:
                    - CUSTOM
                    - EAN
                    - ISBN
                    - ITF
                    - JAN
                    - UPC
                    type: string
                required:
                - code
                type: object
              type: array
            product_suppliers:
              description: 'A list of suppliers and its details if the supplier needs updating. The supplier referenced by this subset must be a supplier associated to the product family.

                '
              items:
                $ref: '#/components/schemas/ProductUpdate21Supplier'
              type: array
            variant_attribute_values:
              description: A list of values for the variant attributes defined for the product. The attributes used here must match the product family.
              items:
                properties:
                  attribute_id:
                    description: The variant attribute id. This variant attribute must be an attribute on the product family.
                    type: string
                  attribute_value:
                    description: The value for the variant attribute.
                    type: string
                required:
                - attribute_id
                - attribute_value
                type: object
              type: array
            weight:
              description: The weight of the product. If provided, weight_unit for this value must also be provided.
              type: number
            weight_unit:
              description: The unit for the weight provided.
              enum:
              - CT
              - G
              - OZ
              - LB
              - KG
              type: string
            width:
              description: The width of the product. If provided, dimensions_unit for this value must also be provided.
              type: number
          type: object
      title: Product Update 2.1 Request
      type: object
    ProductSupplier:
      properties:
        code:
          description: The code associated with this supplier.
          type:
          - string
          - 'null'
        id:
          description: Auto-generated object ID.
          format: UUID
          type: string
        price:
          description: The price associated with this supplier.
          format: double
          type:
          - number
          - 'null'
        product_id:
          description: The ID of the product.
          format: UUID
          type: string
        supplier_id:
          description: The ID of the supplier.
          format: UUID
          type:
          - string
          - 'null'
        supplier_name:
          description: The name of the supplier.
          type:
          - string
          - 'null'
      required:
      - id
      - product_id
      - supplier_id
      - supplier_name
      title: Product Supplier
      type: object
    Product:
      properties:
        account_code:
          description: ???
          type:
          - string
          - 'null'
        account_code_purchase:
          description: ???
          type:
          - string
          - 'null'
        active:
          description: Indicated whether the Product is active.
          type: boolean
        attributes:
          description: A list of attributes
          items:
            $ref: '#/components/schemas/ProductAttribute'
          type: array
        brand:
          $ref: '#/components/schemas/BrandSample'
        brand_id:
          description: The brand ID.
          format: UUID
          type:
          - string
          - 'null'
        button_order:
          description: ???
          type: integer
        categories:
          description: A list of tag objects.
          items:
            $ref: '#/components/schemas/Tag'
          type: array
        composite_bom:
          description: A bill of materials object. This field is only relevant for composite products. It is a map of product ids to the quantity of each product that is needed to make up the composite product.
          type: object
        created_at:
          description: Creation timestamp in UTC.
          type: string
        customizations:
          description: A list of product family customization input fields.
          items:
            type: object
          type: array
        deleted_at:
          description: Deletion timestamp in UTC.
          type:
          - string
          - 'null'
        description:
          description: A detailed description of the Product. **Note** Can contain HTML.
          type:
          - string
          - 'null'
        dimensions_unit:
          description: Unit of measurement for product dimensi

# --- truncated at 32 KB (60 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/lightspeed/refs/heads/main/openapi/lightspeed-products-api-openapi.yml