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 Brands 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: Brand operations
  name: Brands
paths:
  /brands:
    get:
      description: 'Returns a paginated list of brands.


        🔒 Requires: `products:read` scope'
      operationId: ListBrands
      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: The maximum number of items to be returned in the response.
        in: query
        name: page_size
        schema:
          type: integer
      - description: Indicates whether deleted items should be included in the response.
        in: query
        name: deleted
        schema:
          type: boolean
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                - id: 0adaafb3-6583-11e5-fb60-d5b67a17df2f
                  name: Peak Performance
                - id: 0adaafb3-6583-11e5-fb60-ebae84675ae4
                  name: Sennheiser
                - id: b1e2624f-f019-11e3-a0f5-b8ca3a64f8f4
                  name: Generic Brand
              schema:
                $ref: '#/components/schemas/BrandCollection'
          description: OK
      summary: List brands
      tags:
      - Brands
    post:
      description: 'Creates a new brand.


        🔒 Requires: `products:write` scope'
      operationId: CreateBrand
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BrandBase'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    description: The id of brand created.
                    format: uuid
                    type: string
                type: object
          description: OK
      summary: Create brand
      tags:
      - Brands
  /brands/{brand_id}:
    delete:
      description: 'Deletes a brand. If there are products associated with the brand, the products will be disassociated from the brand.


        🔒 Requires: `products:write` scope'
      operationId: DeleteBrandByID
      parameters:
      - description: The brand id.
        in: path
        name: brand_id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  payload:
                    properties:
                      data:
                        properties:
                          id:
                            description: The id of the brand deleted.
                            format: UUID
                            type: string
                          job_id:
                            description: The id of the asynchronous job to disassociate products from the deleted brand.
                            type: string
                        type: object
                    type: object
                type: object
          description: The deleted brand.
      summary: Delete a single brand
      tags:
      - Brands
    get:
      description: 'Returns a single brand with a requested ID


        🔒 Requires: `products:read` scope'
      operationId: GetBrandByID
      parameters:
      - description: The brand id
        in: path
        name: brand_id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BrandResponse'
            new:
              example:
                data:
                  id: 0adaafb3-6583-11e5-fb60-d5b67a17df2f
                  name: Peak Performance
                  version: 882391722
          description: ''
      summary: Get a single brand
      tags:
      - Brands
    put:
      description: '🔒 Requires: `products:write` scope'
      operationId: UpdateBrandById
      parameters:
      - description: The brand id.
        in: path
        name: brand_id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BrandBase'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    properties:
                      id:
                        description: The id of the brand.
                        format: uuid
                        type: string
                    type: object
                type: object
          description: The updated brand.
      summary: Update a single brand
      tags:
      - Brands
components:
  schemas:
    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
    BrandResponse:
      properties:
        data:
          $ref: '#/components/schemas/Brand'
      title: Brand Response
      type: object
    BrandBase:
      properties:
        description:
          description: The brand description.
          type: string
        name:
          description: The Brand name.
          type: string
      required:
      - name
      title: Brand
      type: object
    Brand:
      properties:
        deleted_at:
          description: Deletion timestamp in UTC.
          type:
          - string
          - 'null'
        description:
          description: The brand description.
          type:
          - string
          - 'null'
        id:
          description: Auto-generated object ID.
          type: string
        name:
          description: The brand name.
          type: string
        version:
          description: Auto-incrementing object version number.
          format: int64
          type: integer
      required:
      - name
      - id
      title: Brand
      type: object
    BrandCollection:
      properties:
        data:
          description: An array of Brand objects wrapped in top level `data` object.
          items:
            $ref: '#/components/schemas/Brand'
          type: array
        version:
          $ref: '#/components/schemas/Version'
      required:
      - data
      - version
      title: Brand Collection
      type: object
  securitySchemes:
    bearerAuth:
      description: Bearer Token for API authentication.
      scheme: bearer
      type: http
externalDocs:
  description: List of tz database time zones
  url: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones