Lightspeed Commerce

Lightspeed Commerce Customers API

Customer operations

GitHub OpenAPI
Business capability
Customer Data Management BC-420.10

Operations 5

Each operation below carries the questions people ask an LLM about it and the instructions they give an agent to run it. Generated by API Evangelist overlay

GET /customers List customers · List customers #
Ask an LLM
“How do I list all the customers in my store?”
“Can I include deleted customers when listing them?”
Tell an agent
List my customers, {page_size} per page.
List customers including deleted ones: {deleted}.
POST /customers Create a new customer · Create a new customer #
Ask an LLM
“How do I add a new customer record with their email and phone?”
“Can I enroll a new customer in loyalty when I create them?”
Tell an agent
Create a customer named {first_name} {last_name} with email {email}.
Add new customer {first_name} {last_name} to group {customer_group_id} with loyalty enabled {enable_loyalty}.
DELETE /customers/{customer_id} Delete a customer · Delete a customer #
Ask an LLM
“How do I delete a customer record?”
“Can I remove a duplicate customer from the store?”
Tell an agent destructive · confirm first
Delete customer {customer_id}.
Remove the duplicate customer record {customer_id}.
GET /customers/{customer_id} Get a single customer · Get a single customer #
Ask an LLM
“How do I look up a customer's full record by ID?”
“What contact details do we have for a specific customer?”
Tell an agent
Get customer {customer_id}.
Show the contact details for customer {customer_id}.
PUT /customers/{customer_id} Update a customer's details · Update a customer #
Ask an LLM
“How do I change an existing customer's email or phone number?”
“Can I opt an existing customer out of marketing emails?”
Tell an agent
Update existing customer {customer_id} named {first_name} {last_name} with mobile {mobile}.
Set do-not-email to {do_not_email} on customer {customer_id}.

Documentation

📖
Documentation
https://x-series-api.lightspeedhq.com/docs/introduction
📖
APIReference
https://x-series-api.lightspeedhq.com/reference
📖
GettingStarted
https://x-series-api.lightspeedhq.com/docs/quick_start
📖
Documentation
https://api-portal.lsk.lightspeed.app/
📖
APIReference
https://api-docs.lsk.lightspeed.app/
📖
GettingStarted
https://api-portal.lsk.lightspeed.app/quick-start/intro

Specifications

⚙
OpenAPI
https://artifacts.apis.io/lightspeed/openapi/lightspeed-customers-api-openapi.yml

Schemas & Data

📊
JSONSchema
https://artifacts.apis.io/lightspeed/json-schema/lightspeed-customer-base-schema.json
📊
JSONSchema
https://artifacts.apis.io/lightspeed/json-schema/lightspeed-customer-collection-schema.json
📊
JSONSchema
https://artifacts.apis.io/lightspeed/json-schema/lightspeed-customer-response-schema.json

Other Resources

🔗
ChangeLog
https://x-series-api.lightspeedhq.com/changelog
🔗
LLMsTxt
https://artifacts.apis.io/lightspeed/llms/lightspeed-llms.txt
🔗
SignUp
https://developers.retail.lightspeed.app/register
🔗
ChangeLog
https://api-docs.lsk.lightspeed.app/changes

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API 
curl "https://apis.io/api/v1/apis/lightspeed:lightspeed-customers-api"
All apis 
curl "https://apis.io/api/v1/apis?limit=25"

Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

lightspeed-customers-api-openapi.yml Raw ↑ 
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 Customers 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: Customer operations
  name: Customers
paths:
  /customers:
    get:
      description: 'Returns a paginated list of customers.


        To search for customers, please have a look at our Search endpoint on what is supported.


        🔒 Requires: `customers:read` scope'
      operationId: ListCustomers
      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:
                - balance: -25840.85
                  company_name: Stark Industries Inc
                  created_at: '2014-10-09T05:20:09+00:00'
                  custom_field_1: test
                  custom_field_2: ''
                  custom_field_3: ''
                  custom_field_4: ''
                  customer_code: Tony-N4ZJ
                  customer_group_id: b1ca8902-f019-11e3-a0f5-b8ca3a64f8f4
                  date_of_birth: '1963-03-03'
                  do_not_email: false
                  email: tony@stark.com
                  enable_loyalty: true
                  enable_promotional_sms: false
                  fax: +001 555 12345345
                  first_name: Anthony
                  gender: M
                  id: b8ca3a65-0183-11e4-fbb5-4f73f02a9d1c
                  last_name: Stark
                  loyalty_balance: 5809.64
                  mobile: +001 485 23456789
                  name: Anthony Stark
                  note: ''
                  on_account_limit: 1000
                  phone: +001 555 12345678
                  physical_address_1: Street 1
                  physical_address_2: Street 2
                  physical_city: Los Angeles
                  physical_country_id: NZ
                  physical_postcode: '23422'
                  physical_state: California
                  physical_suburb: Suburb
                  postal_address_1: Street 1
                  postal_address_2: Street 2
                  postal_city: Los Angeles
                  postal_country_id: NZ
                  postal_postcode: '23422'
                  postal_state: California
                  postal_suburb: Suburb
                  twitter: '@ironman'
                  updated_at: '2017-01-19T16:49:35+00:00'
                  version: 2691964626
                  website: http://www.starkinc.com
                  year_to_date: 0
                - balance: 0
                  created_at: '2017-02-13T17:33:25+00:00'
                  customer_code: UNNAMED-669D
                  customer_group_id: b1ca8902-f019-11e3-a0f5-b8ca3a64f8f4
                  do_not_email: false
                  enable_loyalty: true
                  enable_promotional_sms: false
                  first_name: null
                  id: 06bf537b-c783-11e6-ff13-f21286299973
                  last_name: null
                  loyalty_balance: 0
                  on_account_limit: null
                  updated_at: '2017-02-13T17:33:25+00:00'
                  version: 2847386277
                  year_to_date: 0
              schema:
                $ref: '#/components/schemas/CustomerCollection'
          description: ''
      summary: List customers
      tags:
      - Customers
    post:
      description: 'Creates a new customer.


        🔒 Requires: `customers:write` scope'
      operationId: CreateCustomer
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomerBase'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerResponse'
            new:
              example:
                data:
                  balance: 0
                  created_at: '2017-05-24T01:53:25+00:00'
                  customer_code: Tony-37YP
                  customer_group_id: b1ca8902-f019-11e3-a0f5-b8ca3a64f8f4
                  do_not_email: false
                  email: tony@starkinc.com
                  enable_loyalty: true
                  enable_promotional_sms: false
                  first_name: Tony
                  id: 0af7b240-ab83-11e7-eddc-4023c64c85e5
                  last_name: Stark
                  loyalty_balance: 0
                  name: Tony Stark
                  tax_id: null
                  updated_at: '2017-05-24T01:53:25+00:00'
                  version: 3505346597
                  year_to_date: 0
          description: ''
      summary: Create a new customer
      tags:
      - Customers
  /customers/{customer_id}:
    delete:
      description: 'Deletes the customer with the requested ID.


        🔒 Requires: `customers:write` scope'
      operationId: DeleteCustomerByID
      parameters:
      - description: The customer id
        in: path
        name: customer_id
        required: true
        schema:
          type: string
      responses:
        '204':
          description: ''
      summary: Delete a customer
      tags:
      - Customers
    get:
      description: 'Returns a single customer with a requested ID.


        🔒 Requires: `customers:read` scope'
      operationId: GetCustomerByID
      parameters:
      - description: The customer id
        in: path
        name: customer_id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  balance: -25840.85
                  company_name: Stark Industries Inc
                  created_at: '2014-10-09T05:20:09+00:00'
                  custom_field_1: test
                  custom_field_2: ''
                  custom_field_3: ''
                  custom_field_4: ''
                  customer_code: Tony-N4ZJ
                  customer_group_id: b1ca8902-f019-11e3-a0f5-b8ca3a64f8f4
                  date_of_birth: '1963-03-03'
                  do_not_email: false
                  email: tony@stark.com
                  enable_loyalty: true
                  enable_promotional_sms: false
                  fax: +001 555 12345345
                  first_name: Anthony
                  gender: M
                  id: b8ca3a65-0183-11e4-fbb5-4f73f02a9d1c
                  last_name: Stark
                  loyalty_balance: 5809.64
                  mobile: +001 485 23456789
                  name: Anthony Stark
                  note: ''
                  phone: +001 555 12345678
                  physical_address_1: Street 1
                  physical_address_2: Street 2
                  physical_city: Los Angeles
                  physical_country_id: NZ
                  physical_postcode: '23422'
                  physical_state: California
                  physical_suburb: Suburb
                  postal_address_1: Street 1
                  postal_address_2: Street 2
                  postal_city: Los Angeles
                  postal_country_id: NZ
                  postal_postcode: '23422'
                  postal_state: California
                  postal_suburb: Suburb
                  twitter: '@ironman'
                  updated_at: '2017-01-19T16:49:35+00:00'
                  version: 2691964626
                  website: http://www.starkinc.com
                  year_to_date: 0
              schema:
                $ref: '#/components/schemas/CustomerResponse'
          description: ''
      summary: Get a single customer
      tags:
      - Customers
    put:
      description: 'Updates the customer with the requested ID.


        🔒 Requires: `customers:write` scope'
      operationId: UpdateCustomerByID
      parameters:
      - description: The customer id
        in: path
        name: customer_id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomerBase'
        required: true
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  balance: 0
                  company_name: Stark Inc.
                  created_at: '2017-05-24T02:02:18+00:00'
                  custom_field_1: Custom value 1
                  custom_field_2: Custom value 2
                  custom_field_3: Custom value 3
                  custom_field_4: Custom value 4
                  customer_code: Tony-AB2W
                  customer_group_id: b1ca8902-f019-11e3-a0f5-b8ca3a64f8f4
                  do_not_email: false
                  email: tony@starkinc.com
                  enable_loyalty: true
                  enable_promotional_sms: false
                  first_name: Tony
                  id: 0af7b240-ab83-11e7-eddc-4025043113d5
                  last_name: Stark
                  loyalty_balance: 0
                  name: Tony Stark
                  tax_id: null
                  updated_at: '2017-05-24T02:03:59+00:00'
                  version: 3505431251
                  year_to_date: 0
              schema:
                $ref: '#/components/schemas/CustomerResponse'
          description: ''
      summary: Update a customer
      tags:
      - Customers
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
    CustomerCollection:
      properties:
        data:
          description: An array of Customer objects.
          items:
            $ref: '#/components/schemas/Customer'
          type: array
        version:
          $ref: '#/components/schemas/Version'
      title: Customer Collection
      type: object
    CustomerResponse:
      properties:
        data:
          $ref: '#/components/schemas/Customer'
      title: Customer Response
      type: object
    Customer:
      properties:
        balance:
          description: Customer's unpaid balance.
          format: double
          type: number
        company_name:
          description: Company name.
          type:
          - string
          - 'null'
        created_at:
          description: Creation timestamp in UTC.
          type: string
        custom_field_1:
          description: Custom field 1. Can be used to store random data.
          type:
          - string
          - 'null'
        custom_field_2:
          description: Custom field 2.
          type:
          - string
          - 'null'
        custom_field_3:
          description: Custom field 3.
          type:
          - string
          - 'null'
        custom_field_4:
          description: Custom field 4.
          type:
          - string
          - 'null'
        customer_code:
          description: Customer code used for claiming loyalty.
          type: string
        customer_group_id:
          description: Customer group ID.
          type: string
        date_of_birth:
          description: Birthday.
          type:
          - string
          - 'null'
        deleted_at:
          description: Deletion timestamp in UTC.
          type:
          - string
          - 'null'
        do_not_email:
          default: false
          description: Indicates whether the customer opted out of email communications.
          type: boolean
        email:
          description: Customer's email address.
          type:
          - string
          - 'null'
        enable_loyalty:
          type: boolean
        enable_promotional_sms:
          default: false
          description: Indicates whether the customer opted in to SMS communications.
          type: boolean
        fax:
          description: Fax no.
          type:
          - string
          - 'null'
        first_name:
          description: Customer's first name.
          type:
          - string
          - 'null'
        gender:
          description: Customer's gender. Can be `M`, `F` or null.
          type:
          - string
          - 'null'
        id:
          description: Auto-generated object ID.
          type: string
        last_name:
          description: Customer 's last name.
          type:
          - string
          - 'null'
        loyalty_balance:
          description: Customer's loyalty balance.
          format: double
          type: number
        mobile:
          description: Mobile phone no.
          type:
          - string
          - 'null'
        name:
          deprecated: true
          description: Customers full name. **deprecated**
          type:
          - string
          - 'null'
        note:
          description: Customer note.
          type:
          - string
          - 'null'
        on_account_limit:
          description: Customer's OnAccount Limit.
          format: double
          type:
          - number
          - 'null'
        phone:
          description: Phone no.
          type:
          - string
          - 'null'
        physical_address_1:
          description: Physical address, line 1.
          type:
          - string
          - 'null'
        physical_address_2:
          description: Physical address, line 2.
          type:
          - string
          - 'null'
        physical_city:
          description: Physical address, city.
          type:
          - string
          - 'null'
        physical_country_id:
          description: Physical address, country code.
          type:
          - string
          - 'null'
        physical_postcode:
          description: Physical address, post code.
          type:
          - string
          - 'null'
        physical_state:
          description: Physical address, state.
          type:
          - string
          - 'null'
        physical_suburb:
          description: Physical address, suburb.
          type:
          - string
          - 'null'
        postal_address_1:
          description: Postal address, line 1.
          type:
          - string
          - 'null'
        postal_address_2:
          description: Postal address, line 2.
          type:
          - string
          - 'null'
        postal_city:
          description: Postal address, city.
          type:
          - string
          - 'null'
        postal_country_id:
          description: Postal address, country code.
          type:
          - string
          - 'null'
        postal_postcode:
          description: Postal address, post code.
          type:
          - string
          - 'null'
        postal_state:
          description: Postal address, state.
          type:
          - string
          - 'null'
        postal_suburb:
          description: Postal address, suburb.
          type:
          - string
          - 'null'
        tax_id:
          description: Customer's tax ID.
          type:
          - string
          - 'null'
        twitter:
          description: Twitter handle.
          type:
          - string
          - 'null'
        updated_at:
          description: Last update timestamp in UTC.
          type: string
        version:
          description: Auto-incrementing object version number.
          format: int64
          type: integer
        website:
          description: Website URL.
          type:
          - string
          - 'null'
        year_to_date:
          description: Customer's spending this year.
          format: double
          type: number
      required:
      - first_name
      - last_name
      title: Customer
      type: object
    CustomerBase:
      properties:
        company_name:
          description: Company name.
          type:
          - string
          - 'null'
        custom_field_1:
          description: Custom field 1. Can be used to store random data.
          type:
          - string
          - 'null'
        custom_field_2:
          description: Custom field 2.
          type:
          - string
          - 'null'
        custom_field_3:
          description: Custom field 3.
          type:
          - string
          - 'null'
        custom_field_4:
          description: Custom field 4.
          type:
          - string
          - 'null'
        customer_code:
          description: Customer code used for claiming loyalty.
          type: string
        customer_group_id:
          description: Customer group ID.
          type: string
        date_of_birth:
          description: Birthday.
          type: string
        do_not_email:
          default: false
          description: Indicates whether the customer opted out of email communications.
          type: boolean
        email:
          description: Customer's email address.
          type:
          - string
          - 'null'
        enable_loyalty:
          type: boolean
        enable_promotional_sms:
          default: false
          description: Indicates whether the customer opted in to SMS communications.
          type: boolean
        fax:
          description: Fax no.
          type:
          - string
          - 'null'
        first_name:
          description: Customer's first name.
          type:
          - string
          - 'null'
        gender:
          description: Customer's gender. Can be `M`, `F` or null.
          type:
          - string
          - 'null'
        last_name:
          description: Customer 's last name.
          type:
          - string
          - 'null'
        mobile:
          description: Mobile phone no.
          type:
          - string
          - 'null'
        note:
          description: Customer note.
          type:
          - string
          - 'null'
        on_account_limit:
          description: Customer's OnAccount Limit.
          format: double
          type:
          - number
          - 'null'
        phone:
          description: Phone no.
          type:
          - string
          - 'null'
        physical_address_1:
          description: Physical address, line 1.
          type:
          - string
          - 'null'
        physical_address_2:
          description: Physical address, line 2.
          type:
          - string
          - 'null'
        physical_city:
          description: Physical address, city.
          type:
          - string
          - 'null'
        physical_country_id:
          description: Physical address, country code.
          type:
          - string
          - 'null'
        physical_postcode:
          description: Physical address, post code.
          type:
          - string
          - 'null'
        physical_state:
          description: Physical address, state.
          type:
          - string
          - 'null'
        physical_suburb:
          description: Physical address, suburb.
          type:
          - string
          - 'null'
        postal_address_1:
          description: Postal address, line 1.
          type:
          - string
          - 'null'
        postal_address_2:
          description: Postal address, line 2.
          type:
          - string
          - 'null'
        postal_city:
          description: Postal address, city.
          type:
          - string
          - 'null'
        postal_country_id:
          description: Postal address, country code.
          type:
          - string
          - 'null'
        postal_postcode:
          description: Postal address, post code.
          type:
          - string
          - 'null'
        postal_state:
          description: Postal address, state.
          type:
          - string
          - 'null'
        postal_suburb:
          description: Postal address, suburb.
          type:
          - string
          - 'null'
        tax_id:
          description: Customer's tax ID.
          type:
          - string
          - 'null'
        twitter:
          description: Twitter handle.
          type:
          - string
          - 'null'
        website:
          description: Website URL.
          type:
          - string
          - 'null'
      required:
      - first_name
      - last_name
      title: Customer Base
      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
x-provenance:
  method: harvested
  publisher: Lightspeed Commerce
  source: https://x-series-api.lightspeedhq.com/openapi/api-2026-07.yaml
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)