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 Registers 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: Register operations
  name: Registers
paths:
  /button_layouts:
    get:
      description: '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'
      operationId: ListButtonLayouts
      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:
              schema:
                $ref: '#/components/schemas/ButtonLayoutCollection'
          description: A versioned collection of ButtonLayout
      summary: List button layouts
      tags:
      - Registers
  /button_layouts/{button_layout_id}:
    get:
      description: 'Returns a single button layout by id.

        Button layouts define the arrangement of quick key buttons on a register.


        🔒 Requires: `registers:read` scope'
      operationId: GetButtonLayoutById
      parameters:
      - description: UUID of the button layout
        in: path
        name: button_layout_id
        required: true
        schema:
          format: uuid
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ButtonLayout'
          description: A single ButtonLayout wrapped in a data object
        '404':
          content:
            application/json:
              schema:
                type: object
          description: ButtonLayout not found
      summary: Get a single button layout
      tags:
      - Registers
  /registers:
    get:
      description: 'Returns a paginated list of registers.


        🔒 Requires: `registers:read` scope'
      operationId: ListRegisters
      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
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegisterCollection'
            new:
              example:
                data:
                - ask_for_note_on_save: 1
                  ask_for_user_on_sale: false
                  button_layout_id: d656e8e1-7be7-11e4-9bb5-b8ca3a65011c
                  cash_managed_payment_type_id: b1e1d70e-f019-11e3-a0f5-b8ca3a64f8f4
                  email_receipt: true
                  id: b1e198a9-f019-11e3-a0f5-b8ca3a64f8f4
                  invoice_prefix: MR-
                  invoice_sequence: 1708
                  invoice_suffix: -NZ
                  is_open: true
                  is_quick_keys_enabled: true
                  name: Main Register
                  outlet_id: b1e04bd8-f019-11e3-a0f5-b8ca3a64f8f4
                  print_note_on_receipt: false
                  print_receipt: true
                  receipt_template_id: 0242ac11-0002-11ea-e96b-69ae6c24a799
                  register_open_sequence_id: 06bf537b-c783-11e7-ff13-3157eb615f96
                  register_open_time: '2017-05-05T05:58:53+00:00'
                  show_discounts_on_receipts: true
                  version: 3391483933
                - ask_for_note_on_save: 1
                  ask_for_user_on_sale: false
                  email_receipt: false
                  id: b8ca3a65-0183-11e4-fbb5-2816e25ffc51
                  invoice_prefix: S
                  invoice_sequence: 3
                  invoice_suffix: ''
                  is_open: true
                  is_quick_keys_enabled: true
                  name: Second Register
                  outlet_id: b8ca3a65-0183-11e4-fbb5-2816d2677218
                  print_note_on_receipt: false
                  print_receipt: true
                  receipt_template_id: 0242ac11-0002-11ea-e96b-69ae6c24a799
                  register_open_sequence_id: a0369f1f-9083-11e4-f68e-cc2ad7a415de
                  register_open_time: '2015-03-16T22:21:50+00:00'
                  show_discounts_on_receipts: true
                  version: 709083
                - ask_for_note_on_save: 1
                  ask_for_user_on_sale: false
                  email_receipt: false
                  id: 06e35f89-3783-11e6-ec7e-10e1180eba6d
                  invoice_prefix: Th
                  invoice_sequence: 3
                  invoice_suffix: X
                  is_open: true
                  is_quick_keys_enabled: true
                  name: Third register
                  outlet_id: b8ca3a65-0183-11e4-fbb5-2816d2677218
                  print_note_on_receipt: false
                  print_receipt: true
                  receipt_template_id: 0242ac11-0002-11ea-e96b-69ae6c24a799
                  register_open_sequence_id: 06e35f89-3783-11e6-ec7e-10e124cb1e78
                  register_open_time: '2016-05-03T03:43:04+00:00'
                  show_discounts_on_receipts: true
                  version: 1234541473
                version:
                  max: 3391483933
                  min: 709083
          description: ''
      summary: List registers
      tags:
      - Registers
  /registers/{register_id}:
    get:
      description: 'Returns a single register with the requested ID.


        🔒 Requires: `registers:read` scope'
      operationId: GetRegisterByID
      parameters:
      - description: The register id
        in: path
        name: register_id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  ask_for_note_on_save: 1
                  ask_for_user_on_sale: false
                  email_receipt: false
                  id: b8ca3a65-0183-11e4-fbb5-2816e25ffc51
                  invoice_prefix: S
                  invoice_sequence: 3
                  invoice_suffix: ''
                  is_open: true
                  is_quick_keys_enabled: true
                  name: Second Register
                  outlet_id: b8ca3a65-0183-11e4-fbb5-2816d2677218
                  print_note_on_receipt: false
                  print_receipt: true
                  receipt_template_id: 0242ac11-0002-11ea-e96b-69ae6c24a799
                  register_open_sequence_id: a0369f1f-9083-11e4-f68e-cc2ad7a415de
                  register_open_time: '2015-03-16T22:21:50+00:00'
                  show_discounts_on_receipts: true
                  version: 709083
              schema:
                $ref: '#/components/schemas/RegisterResponse'
          description: ''
      summary: Get a single register
      tags:
      - Registers
  /registers/{register_id}/actions/close:
    put:
      description: 'Closes a single register with the requested ID.


        🔒 Requires: `register:close` `payment_types:read` scopes'
      operationId: CloseRegister
      parameters:
      - description: The register id
        in: path
        name: register_id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RegisterCloseRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  ask_for_note_on_save: 1
                  ask_for_user_on_sale: false
                  email_receipt: false
                  id: b8ca3a65-0183-11e4-fbb5-2816e25ffc51
                  invoice_prefix: S
                  invoice_sequence: 3
                  invoice_suffix: ''
                  is_open: false
                  is_quick_keys_enabled: true
                  name: Second Register
                  outlet_id: b8ca3a65-0183-11e4-fbb5-2816d2677218
                  print_note_on_receipt: false
                  print_receipt: true
                  receipt_template_id: 0242ac11-0002-11ea-e96b-69ae6c24a799
                  register_close_time: '2015-03-16T22:21:50+00:00'
                  show_discounts_on_receipts: true
                  version: 709083
              schema:
                $ref: '#/components/schemas/RegisterResponse'
          description: ''
      summary: Close a single register
      tags:
      - Registers
  /registers/{register_id}/actions/open:
    put:
      description: 'Opens a single register with the requested ID.


        🔒 Requires: `register:open` scope'
      operationId: OpenRegister
      parameters:
      - description: The register id
        in: path
        name: register_id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RegisterOpenRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  ask_for_note_on_save: 1
                  ask_for_user_on_sale: false
                  email_receipt: false
                  id: b8ca3a65-0183-11e4-fbb5-2816e25ffc51
                  invoice_prefix: S
                  invoice_sequence: 3
                  invoice_suffix: ''
                  is_open: true
                  is_quick_keys_enabled: true
                  name: Second Register
                  outlet_id: b8ca3a65-0183-11e4-fbb5-2816d2677218
                  print_note_on_receipt: false
                  print_receipt: true
                  receipt_template_id: 0242ac11-0002-11ea-e96b-69ae6c24a799
                  register_open_sequence_id: a0369f1f-9083-11e4-f68e-cc2ad7a415de
                  register_open_time: '2015-03-16T22:21:50+00:00'
                  show_discounts_on_receipts: true
                  version: 709083
              schema:
                $ref: '#/components/schemas/RegisterResponse'
          description: ''
      summary: Open a single register
      tags:
      - Registers
  /registers/{register_id}/payments_summary:
    get:
      description: 'Returns a payload containing payment totals for all payments types defined in the account for a single register.


        🔒 Requires: `payments:read` scope'
      operationId: RegisterPaymentsSummary
      parameters:
      - description: The register id
        in: path
        name: register_id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  payments:
                  - payment_type_id: 2ac65e3b-1224-4aa5-bedf-936cfe85ac95
                    payment_type_name: Loyalty
                    total: '0.00'
                  - payment_type_id: be21ec2b-315f-1b07-8567-936cfe85ac95
                    payment_type_name: Cash
                    total: '255.00'
                  - payment_type_id: 2ac65e3b-b6c5-6547-9543-80ba85264a8e
                    payment_type_name: Credit Card
                    total: '1038.77'
                  register_closure_id: 0ab9b350-ab7f-11ba-fc5c-6e58d999006f
                  register_closure_sequence_number: 5
                  register_open_time: '2015-03-16T22:21:50+00:00'
              schema:
                $ref: '#/components/schemas/RegisterPaymentsSummaryResponse'
          description: ''
      summary: Get all the payments data associated with a single register.
      tags:
      - Registers
components:
  schemas:
    RegisterClosePaymentType:
      properties:
        payment_type_id:
          description: The ID of the Payment Type.
          type: string
        total:
          description: The Total amount for this Payment Type.
          type: string
      title: Register Close Payment Type
      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
    ButtonLayout:
      properties:
        deletedAt:
          format: date-time
          type:
          - string
          - 'null'
        id:
          description: Autogenerated object identifier.
          type: string
        name:
          description: The name of the button layout.
          type: string
        nodes:
          description: The nodes that make up the button layout.
          items:
            $ref: '#/components/schemas/ButtonLayoutNode'
          type: array
        version:
          description: Auto-incrementing object version number.
          format: int64
          type: integer
      required:
      - id
      - name
      - nodes
      - version
      type: object
    ButtonLayoutNodeAttribute:
      properties:
        key:
          description: The attribute key.
          type: string
        value:
          description: The attribute value.
          type: string
      required:
      - key
      - value
      type: object
    RegisterOpenRequest:
      properties:
        register_open_time:
          description: Date/time when the register was open. Always in UTC.
          type: string
      title: Register Open Request
      type: object
    ButtonLayoutCollection:
      properties:
        data:
          items:
            $ref: '#/components/schemas/ButtonLayout'
          type: array
        pagination:
          $ref: '#/components/schemas/PaginationMetadata'
        version:
          $ref: '#/components/schemas/Version'
      required:
      - data
      - version
      type: object
    RegisterResponse:
      properties:
        data:
          $ref: '#/components/schemas/Register'
      title: Register Response
      type: object
    Register:
      properties:
        ask_for_note_on_save:
          description: '`0` for **Never**, `1` for **On Save/Layby/Account/Return**, `2` for **Always**.'
          format: double
          type: number
        ask_for_user_on_sale:
          type: boolean
        button_layout_id:
          description: Register ID.
          type:
          - string
          - 'null'
        cash_managed_payment_type_id:
          description: '**internal** The ID of the payment type used for cash management transactions in this regsiter.'
          type:
          - string
          - 'null'
        deleted_at:
          description: Deletion timestamp in UTC.
          type:
          - string
          - 'null'
        email_receipt:
          description: Indicates whether a receipt should be emailed after a sale.
          type: boolean
        id:
          description: Auto-generated object ID.
          type: string
        invoice_prefix:
          description: Invoice number prefix.
          type: string
        invoice_sequence:
          description: The numeric part of the last issued invoice.
          format: double
          type: number
        invoice_suffix:
          description: Invoice number suffix.
          type: string
        is_open:
          description: Indicates if the Register is currently open.
          type: boolean
        name:
          description: The Register name.
          type: string
        outlet_id:
          description: A valid ID of an Outlet that this register is associated with.
          type: string
        print_note_on_receipt:
          type: boolean
        print_receipt:
          description: Indicates whether a receipt should be printed after a sale.
          type: boolean
        receipt_template_id:
          description: Default receipt template ID used for this register.
          type: string
        register_close_time:
          description: Date/time when the register was closed. Null if currently open.
          type:
          - string
          - 'null'
        register_open_sequence_id:
          description: '**internal** The ID of the current register closure object.'
          type:
          - string
          - 'null'
        register_open_time:
          description: Date/time when the register was open. Always in UTC.
          type:
          - string
          - 'null'
        show_discounts_on_receipts:
          type: boolean
        version:
          description: Auto-incrementing object version number.
          format: int64
          type: integer
      title: Register
      type: object
    RegisterPaymentSummaryPaymentType:
      properties:
        payment_type_id:
          description: The ID of the Payment Type.
          format: uuid
          type: string
        payment_type_name:
          description: The name of the Payment Type.
          type: string
        total:
          description: The Total amount for this Payment Type.
          type: string
      title: Register Payments Summary Payment Type
      type: object
    RegisterPaymentsSummary:
      properties:
        payments:
          items:
            $ref: '#/components/schemas/RegisterPaymentSummaryPaymentType'
          type: array
      title: Register Payments Summary
      type: object
    PaginationMetadata:
      properties:
        page:
          type: integer
        pageSize:
          type: integer
        results:
          type: integer
      type: object
    RegisterPaymentsSummaryResponse:
      properties:
        data:
          $ref: '#/components/schemas/RegisterPaymentsSummary'
      title: Register Payments Summary Response
      type: object
    RegisterCloseRequest:
      properties:
        payments:
          description: An array Register objects wrapped in a top level `data` object.
          items:
            $ref: '#/components/schemas/RegisterClosePaymentType'
          type: array
      title: Register Close Request
      type: object
    ButtonLayoutNode:
      properties:
        attributes:
          description: The attributes associated with this node.
          items:
            $ref: '#/components/schemas/ButtonLayoutNodeAttribute'
          type: array
        id:
          description: Autogenerated object identifier.
          type: string
        parentNodeId:
          description: The ID of the parent node, if applicable.
          format: uuid
          type:
          - string
          - 'null'
        position:
          description: The position of the node within its parent.
          type: integer
        productId:
          description: The product ID associated with this node, if applicable.
          type:
          - string
          - 'null'
      required:
      - id
      - position
      - attributes
      type: object
    RegisterCollection:
      properties:
        data:
          description: An array Register objects wrapped in a top level `data` object.
          items:
            $ref: '#/components/schemas/Register'
          type: array
        version:
          $ref: '#/components/schemas/Version'
      title: Register 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