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 Users 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: User operations
  name: Users
paths:
  /user:
    get:
      description: 'Returns the current user.


        🔒 Requires: `users:read` scope'
      operationId: GetUser
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                - account_type: admin
                  created_at: '2024-08-11T12:45:44+00:00'
                  deleted_at: null
                  display_name: API User
                  email: x-series.api@lightspeedhq.com
                  email_verified_at: null
                  enabled: true
                  enabled_mfa: null
                  id: b1ed6158-f019-11e3-a0f5-b8ca3a64f8f4
                  image_source: https://vendimageuploadcdn.global.ssl.fastly.net/50x50,q90/vend-images/user/original/1/b/1ba1099aecfbbcbdfc4aa8efb136507f99a3c0d9.jpg
                  images:
                    original: https://vendimageuploadcdn.global.ssl.fastly.net/1920,fit/vend-images/user/original/1/b/1ba1099aecfbbcbdfc4aa8efb136507f99a3c0d9.jpg
                    sl: https://vendimageuploadcdn.global.ssl.fastly.net/150x150,q90/vend-images/user/original/1/b/1ba1099aecfbbcbdfc4aa8efb136507f99a3c0d9.jpg
                    sm: https://vendimageuploadcdn.global.ssl.fastly.net/100x100,q90/vend-images/user/original/1/b/1ba1099aecfbbcbdfc4aa8efb136507f99a3c0d9.jpg
                    ss: https://vendimageuploadcdn.global.ssl.fastly.net/50x50,q90/vend-images/user/original/1/b/1ba1099aecfbbcbdfc4aa8efb136507f99a3c0d9.jpg
                    st: https://vendimageuploadcdn.global.ssl.fastly.net/40x40,q90/vend-images/user/original/1/b/1ba1099aecfbbcbdfc4aa8efb136507f99a3c0d9.jpg
                    standard: https://vendimageuploadcdn.global.ssl.fastly.net/350,fit,q90/vend-images/user/original/1/b/1ba1099aecfbbcbdfc4aa8efb136507f99a3c0d9.jpg
                    thumb: https://vendimageuploadcdn.global.ssl.fastly.net/160,fit,q90/vend-images/user/original/1/b/1ba1099aecfbbcbdfc4aa8efb136507f99a3c0d9.jpg
                  is_primary_user: false
                  permissions:
                  - user.add_edit
                  - user.view
                  require_password_change: false
                  restricted_outlet_id: null
                  restricted_outlet_ids: []
                  roles:
                  - id: 100
                    name: Admin
                    system_role_id: 100
                  rules:
                    sale.line_item_discount.manage:
                      max_discount: 100
                    sale.total_sale_discount.manage:
                      max_discount: 100
                  seen_at: '2024-08-11T23:29:41+00:00'
                  switch_id: usi:3e4b5edaec24
                  target_daily: 1000
                  target_monthly: 20000
                  target_weekly: 5000
                  time_until_deletion: null
                  updated_at: '2016-04-18T15:32:17+00:00'
                  username: apiuser
                  version: 5020
              schema:
                $ref: '#/components/schemas/UserResponse'
          description: ''
      summary: Get current user
      tags:
      - Users
  /users:
    get:
      description: 'Returns a paginated list of users.


        🔒 Requires: `users:read` scope'
      operationId: ListUsers
      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
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                - account_type: admin
                  created_at: '2024-08-11T12:45:44+00:00'
                  deleted_at: null
                  display_name: API User
                  email: x-series.api@lightspeedhq.com
                  email_verified_at: null
                  enabled: true
                  enabled_mfa: null
                  id: b1ed6158-f019-11e3-a0f5-b8ca3a64f8f4
                  image_source: https://vendimageuploadcdn.global.ssl.fastly.net/50x50,q90/vend-images/user/original/1/b/1ba1099aecfbbcbdfc4aa8efb136507f99a3c0d9.jpg
                  images:
                    original: https://vendimageuploadcdn.global.ssl.fastly.net/1920,fit/vend-images/user/original/1/b/1ba1099aecfbbcbdfc4aa8efb136507f99a3c0d9.jpg
                    sl: https://vendimageuploadcdn.global.ssl.fastly.net/150x150,q90/vend-images/user/original/1/b/1ba1099aecfbbcbdfc4aa8efb136507f99a3c0d9.jpg
                    sm: https://vendimageuploadcdn.global.ssl.fastly.net/100x100,q90/vend-images/user/original/1/b/1ba1099aecfbbcbdfc4aa8efb136507f99a3c0d9.jpg
                    ss: https://vendimageuploadcdn.global.ssl.fastly.net/50x50,q90/vend-images/user/original/1/b/1ba1099aecfbbcbdfc4aa8efb136507f99a3c0d9.jpg
                    st: https://vendimageuploadcdn.global.ssl.fastly.net/40x40,q90/vend-images/user/original/1/b/1ba1099aecfbbcbdfc4aa8efb136507f99a3c0d9.jpg
                    standard: https://vendimageuploadcdn.global.ssl.fastly.net/350,fit,q90/vend-images/user/original/1/b/1ba1099aecfbbcbdfc4aa8efb136507f99a3c0d9.jpg
                    thumb: https://vendimageuploadcdn.global.ssl.fastly.net/160,fit,q90/vend-images/user/original/1/b/1ba1099aecfbbcbdfc4aa8efb136507f99a3c0d9.jpg
                  is_primary_user: false
                  permissions: null
                  require_password_change: false
                  restricted_outlet_id: null
                  restricted_outlet_ids: []
                  roles:
                  - id: 100
                    name: Admin
                    system_role_id: 100
                  rules: {}
                  seen_at: '2024-08-11T23:29:41+00:00'
                  switch_id: usi:3e4b5edaec24
                  target_daily: 1000
                  target_monthly: 20000
                  target_weekly: 5000
                  time_until_deletion: null
                  updated_at: '2016-04-18T15:32:17+00:00'
                  username: apiuser
                  version: 5020
                version:
                  max: 3348795492
                  min: 298969
              schema:
                $ref: '#/components/schemas/UserCollection'
          description: ''
      summary: List users
      tags:
      - Users
  /users/bulk:
    post:
      description: 'Get multiple users by id.


        🔒 Requires: `users:read` scope'
      operationId: GetUsersById
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetUsersByIdsRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                - account_type: admin
                  created_at: '2024-08-11T12:45:44+00:00'
                  deleted_at: null
                  display_name: API User
                  email: x-series.api@lightspeedhq.com
                  email_verified_at: null
                  enabled: true
                  enabled_mfa: null
                  id: b1ed6158-f019-11e3-a0f5-b8ca3a64f8f4
                  image_source: https://vendimageuploadcdn.global.ssl.fastly.net/50x50,q90/vend-images/user/original/1/b/1ba1099aecfbbcbdfc4aa8efb136507f99a3c0d9.jpg
                  images:
                    original: https://vendimageuploadcdn.global.ssl.fastly.net/1920,fit/vend-images/user/original/1/b/1ba1099aecfbbcbdfc4aa8efb136507f99a3c0d9.jpg
                    sl: https://vendimageuploadcdn.global.ssl.fastly.net/150x150,q90/vend-images/user/original/1/b/1ba1099aecfbbcbdfc4aa8efb136507f99a3c0d9.jpg
                    sm: https://vendimageuploadcdn.global.ssl.fastly.net/100x100,q90/vend-images/user/original/1/b/1ba1099aecfbbcbdfc4aa8efb136507f99a3c0d9.jpg
                    ss: https://vendimageuploadcdn.global.ssl.fastly.net/50x50,q90/vend-images/user/original/1/b/1ba1099aecfbbcbdfc4aa8efb136507f99a3c0d9.jpg
                    st: https://vendimageuploadcdn.global.ssl.fastly.net/40x40,q90/vend-images/user/original/1/b/1ba1099aecfbbcbdfc4aa8efb136507f99a3c0d9.jpg
                    standard: https://vendimageuploadcdn.global.ssl.fastly.net/350,fit,q90/vend-images/user/original/1/b/1ba1099aecfbbcbdfc4aa8efb136507f99a3c0d9.jpg
                    thumb: https://vendimageuploadcdn.global.ssl.fastly.net/160,fit,q90/vend-images/user/original/1/b/1ba1099aecfbbcbdfc4aa8efb136507f99a3c0d9.jpg
                  is_primary_user: false
                  permissions: null
                  require_password_change: false
                  restricted_outlet_id: null
                  restricted_outlet_ids: []
                  roles:
                  - id: 100
                    name: Admin
                    system_role_id: 100
                  rules: {}
                  seen_at: '2024-08-11T23:29:41+00:00'
                  switch_id: usi:3e4b5edaec24
                  target_daily: 1000
                  target_monthly: 20000
                  target_weekly: 5000
                  time_until_deletion: null
                  updated_at: '2016-04-18T15:32:17+00:00'
                  username: apiuser
                  version: 5020
                version:
                  max: 3348795492
                  min: 298969
              schema:
                $ref: '#/components/schemas/UserCollection'
          description: ''
      summary: Get multiple users by id
      tags:
      - Users
  /users/{user_id}:
    delete:
      description: Returns the user that has been deleted.
      operationId: DeleteUserByID
      parameters:
      - description: A valid user id that is not the current user nor a primary admin
        in: path
        name: user_id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                - account_type: admin
                  created_at: '2024-08-11T12:45:44+00:00'
                  deleted_at: '2024-08-12T16:00:03+00:00'
                  display_name: API User
                  email: x-series.api@lightspeedhq.com
                  email_verified_at: null
                  enabled: true
                  enabled_mfa: null
                  id: b1ed6158-f019-11e3-a0f5-b8ca3a64f8f4
                  image_source: https://vendimageuploadcdn.global.ssl.fastly.net/50x50,q90/vend-images/user/original/1/b/1ba1099aecfbbcbdfc4aa8efb136507f99a3c0d9.jpg
                  images:
                    original: https://vendimageuploadcdn.global.ssl.fastly.net/1920,fit/vend-images/user/original/1/b/1ba1099aecfbbcbdfc4aa8efb136507f99a3c0d9.jpg
                    sl: https://vendimageuploadcdn.global.ssl.fastly.net/150x150,q90/vend-images/user/original/1/b/1ba1099aecfbbcbdfc4aa8efb136507f99a3c0d9.jpg
                    sm: https://vendimageuploadcdn.global.ssl.fastly.net/100x100,q90/vend-images/user/original/1/b/1ba1099aecfbbcbdfc4aa8efb136507f99a3c0d9.jpg
                    ss: https://vendimageuploadcdn.global.ssl.fastly.net/50x50,q90/vend-images/user/original/1/b/1ba1099aecfbbcbdfc4aa8efb136507f99a3c0d9.jpg
                    st: https://vendimageuploadcdn.global.ssl.fastly.net/40x40,q90/vend-images/user/original/1/b/1ba1099aecfbbcbdfc4aa8efb136507f99a3c0d9.jpg
                    standard: https://vendimageuploadcdn.global.ssl.fastly.net/350,fit,q90/vend-images/user/original/1/b/1ba1099aecfbbcbdfc4aa8efb136507f99a3c0d9.jpg
                    thumb: https://vendimageuploadcdn.global.ssl.fastly.net/160,fit,q90/vend-images/user/original/1/b/1ba1099aecfbbcbdfc4aa8efb136507f99a3c0d9.jpg
                  is_primary_user: false
                  permissions: null
                  require_password_change: false
                  restricted_outlet_id: null
                  restricted_outlet_ids: []
                  roles:
                  - id: 100
                    name: Admin
                    system_role_id: 100
                  rules: {}
                  seen_at: '2024-08-11T23:29:41+00:00'
                  switch_id: usi:3e4b5edaec24
                  target_daily: 1000
                  target_monthly: 20000
                  target_weekly: 5000
                  time_until_deletion: null
                  updated_at: '2016-04-18T15:32:17+00:00'
                  username: apiuser
                  version: 5020
                version:
                  max: 3348795492
                  min: 298969
              schema:
                $ref: '#/components/schemas/UserResponse'
          description: ''
        '403':
          content:
            application/json:
              example:
                error: permission denied
          description: Forbidden
        '404':
          content:
            application/json:
              example:
                error: user not found
          description: Not Found
      summary: Delete a single user
      tags:
      - Users
    get:
      description: 'Returns a single user with the requested ID.


        🔒 Requires: `users:read` scope'
      operationId: GetUserByID
      parameters:
      - description: A valid user id
        in: path
        name: user_id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                - account_type: admin
                  created_at: '2024-08-11T12:45:44+00:00'
                  deleted_at: null
                  display_name: API User
                  email: x-series.api@lightspeedhq.com
                  email_verified_at: null
                  enabled: true
                  enabled_mfa: null
                  id: b1ed6158-f019-11e3-a0f5-b8ca3a64f8f4
                  image_source: https://vendimageuploadcdn.global.ssl.fastly.net/50x50,q90/vend-images/user/original/1/b/1ba1099aecfbbcbdfc4aa8efb136507f99a3c0d9.jpg
                  images:
                    original: https://vendimageuploadcdn.global.ssl.fastly.net/1920,fit/vend-images/user/original/1/b/1ba1099aecfbbcbdfc4aa8efb136507f99a3c0d9.jpg
                    sl: https://vendimageuploadcdn.global.ssl.fastly.net/150x150,q90/vend-images/user/original/1/b/1ba1099aecfbbcbdfc4aa8efb136507f99a3c0d9.jpg
                    sm: https://vendimageuploadcdn.global.ssl.fastly.net/100x100,q90/vend-images/user/original/1/b/1ba1099aecfbbcbdfc4aa8efb136507f99a3c0d9.jpg
                    ss: https://vendimageuploadcdn.global.ssl.fastly.net/50x50,q90/vend-images/user/original/1/b/1ba1099aecfbbcbdfc4aa8efb136507f99a3c0d9.jpg
                    st: https://vendimageuploadcdn.global.ssl.fastly.net/40x40,q90/vend-images/user/original/1/b/1ba1099aecfbbcbdfc4aa8efb136507f99a3c0d9.jpg
                    standard: https://vendimageuploadcdn.global.ssl.fastly.net/350,fit,q90/vend-images/user/original/1/b/1ba1099aecfbbcbdfc4aa8efb136507f99a3c0d9.jpg
                    thumb: https://vendimageuploadcdn.global.ssl.fastly.net/160,fit,q90/vend-images/user/original/1/b/1ba1099aecfbbcbdfc4aa8efb136507f99a3c0d9.jpg
                  is_primary_user: false
                  permissions: null
                  require_password_change: false
                  restricted_outlet_id: null
                  restricted_outlet_ids: []
                  roles:
                  - id: 100
                    name: Admin
                    system_role_id: 100
                  rules: {}
                  seen_at: '2024-08-11T23:29:41+00:00'
                  switch_id: usi:3e4b5edaec24
                  target_daily: 1000
                  target_monthly: 20000
                  target_weekly: 5000
                  time_until_deletion: null
                  updated_at: '2016-04-18T15:32:17+00:00'
                  username: apiuser
                  version: 5020
                version:
                  max: 3348795492
                  min: 298969
              schema:
                $ref: '#/components/schemas/UserResponse'
          description: ''
      summary: Get a single user
      tags:
      - Users
  /users/{user_id}/sale_totals:
    get:
      description: Returns a single user's sales totals.
      operationId: GetSalesTotalsForUserByID
      parameters:
      - description: A valid user id
        in: path
        name: user_id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                - cost: 0
                  date_from: '2024-08-11T12:00:00+00:00'
                  date_to: '2024-08-12T11:59:59+00:00'
                  discounts: 0
                  label: today
                  loyalty: 0
                  revenue: 0
                  sale_count: 0
                  tax: 0
                  total: 0
                - cost: 0
                  date_from: '2024-07-31T12:00:00+00:00'
                  date_to: '2024-08-12T11:59:59+00:00'
                  discounts: 0
                  label: month
                  loyalty: 0
                  revenue: 0
                  sale_count: 0
                  tax: 0
                  total: 0
              schema:
                $ref: '#/components/schemas/UserSaleTotalResponse'
          description: ''
      summary: Get the sales totals for a single user
      tags:
      - Users
  /users/{user_id}/sessions:
    delete:
      description: 'Deletes all sessions and personal tokens of the given user.


        🔒 Requires: `users:write` scope'
      operationId: DeleteSessionsByUserID
      parameters:
      - description: A valid user id
        in: path
        name: user_id
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
      summary: Delete user sessions
      tags:
      - Users
components:
  schemas:
    UserCollection:
      properties:
        data:
          description: An array of users.
          items:
            $ref: '#/components/schemas/User'
          type: array
        version:
          $ref: '#/components/schemas/Version'
      required:
      - data
      - version
      title: User Collection
      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
    UserResponse:
      description: A response for a single user GET request.
      properties:
        data:
          $ref: '#/components/schemas/User'
      title: User Response
      type: object
    UserSaleTotalResponse:
      properties:
        data:
          items:
            $ref: '#/components/schemas/UserSaleTotalCollection'
          type: array
      title: User Sale Total Response
      type: object
    Role:
      properties:
        id:
          description: Auto-generated object ID.
          type: string
        name:
          description: The Role name.
          type: string
        system_role_id:
          description: A system role id of the Role. Will be either '100', '200', or '300'.
          type: string
      title: Role
      type: object
    UserSaleTotalCollection:
      properties:
        cost:
          description: The cost total of sales for the user.
          format: double
          type: number
        date_from:
          description: From timestamp in UTC.
          type: string
        date_to:
          description: To timestamp in UTC.
          type: string
        discounts:
          description: The discounts total of sales for the user.
          format: double
          type: number
        label:
          description: The label for what the total represents.
          type: string
        loyalty:
          description: The loyalty total of sales for the user.
          format: double
          type: number
        revenue:
          description: The revenue total of sales for the user.
          format: double
          type: number
        sale_count:
          description: The total number of sales for the user.
          format: integer
          type: number
        tax:
          description: The tax total of sales for the user.
          format: double
          type: number
        total:
          description: The total sales for the user.
          format: double
          type: number
      title: User Sale Total Collection
      type: object
    GetUsersByIdsRequest:
      description: An array of user IDs to retrieve.
      items:
        format: uuid
        type: string
      title: GetUsersByIdsRequest
      type: array
    User:
      properties:
        account_type:
          description: User's account type.
          enum:
          - cashier
          - manager
          - admin
          type: string
        created_at:
          description: Creation timestamp in UTC.
          type: string
        deleted_at:
          description: Deletion timestamp in UTC.
          type:
          - string
          - 'null'
        display_name:
          description: Full user's name to be used for display in the UI.
          type:
          - string
          - 'null'
        email:
          description: User's email address.
          format: email
          type:
          - string
          - 'null'
        email_verified_at:
          description: The timestamp of users email verification.
          type:
          - string
          - 'null'
        enabled:
          description: Indicates whether the user is enabled.
          type: boolean
        enabled_mfa:
          description: The user's enabled MFA factor, or null if MFA is not enabled.
          properties:
            created_at:
              description: Timestamp when the MFA factor was created.
              type: string
            id:
              description: Auto-generated MFA factor ID.
              type: string
            type:
              description: The MFA factor type (e.g. "otp").
              enum:
              - otp
              type: string
          type:
          - object
          - 'null'
        id:
          description: Auto-generated object ID.
          format: uuid
          type: string
        image_source:
          description: URL of the default-sized user's avatar.
          type: string
        images:
          $ref: '#/components/schemas/UserImages'
        is_primary_user:
          description: Indicated whether this user is the primary user for the account.
          type: boolean
        permissions:
          description: The permissions assigned to the user.
          items:
            type: string
          type:
          - array
          - 'null'
        require_password_change:
          description: Indicates whether the user is required to change their password.
          type: boolean
        restricted_outlet_id:
          deprecated: true
          description: '**deprecated** Use the `restricted_outlet_ids` instead.'
          type:
          - string
          - 'null'
        restricted_outlet_ids:
          description: A list of outlet IDs the user is associated with
          items:
            format: uuid
            type: string
          type: array
        roles:
          description: The roles assigned to the user.
          items:
            $ref: '#/components/schemas/Role'
          type: array
        rules:
          description: The rules assigned to the user.
          type: object
        seen_at:
          description: The timestamp of the user's last activity in the system.
          type: string
        switch_id:
          description: The switch id for the user.
          type: string
        target_daily:
          description: Daily sales target for the user.
          type:
          - number
          - 'null'
        target_monthly:
          description: Monthly sales target for the user.
          type:
          - number
          - 'null'
        target_weekly:
          description: Weekly sales target for the user.
          type:
          - number
          - 'null'
        time_until_deletion:
          description: The time until the user is deleted.
          type:
          - string
          - 'null'
        updated_at:
          description: Last update timestamp in UTC.
          type: string
        username:
          description: User's username used for login.
          type: string
        version:
          description: Auto-incrementing object version number.
          format: int64
          type: integer
      required:
      - account_type
      - created_at
      - id
      - is_primary_user
      - updated_at
      - username
      - version
      title: User
      type: object
    UserImages:
      description: On object containing URLs for different sizes of the user’s avatar.
      properties:
        original:
          type: string
        sl:
          type: string
        sm:
          type: string
        ss:
          type: string
        st:
          type: string
        standard:
          type: string
        thumb:
          type: string
      title: User Image
      type:
      - object
      - 'null'
  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