Lightspeed Retail X-Series API

https://x-series-api.lightspeedhq.com/reference/listcustomers
Admin
Lightspeed Retail X-Series API is a REST API that enables developers to integrate with and manage...
Tokens:3,728
Snippets:6
Trust Score:10
Update:5 months ago
Show doc for...
Tokens:
Raw
### List Customers

Source: https://x-series-api.lightspeedhq.com/reference/listcustomers

Returns a paginated list of customers. Requires the `customers:read` scope.

```APIDOC
## GET /customers

### Description
Returns a paginated list of customers.

### Method
GET

### Endpoint
/customers

### Query Parameters
- **limit** (integer) - Optional - The maximum number of customers to return.
- **offset** (integer) - Optional - The number of customers to skip before returning results.

### Scopes
- `customers:read`
```

--------------------------------

### List Customers OpenAPI Definition

Source: https://x-series-api.lightspeedhq.com/reference/listcustomers

This JSON snippet defines the OpenAPI specification for the ListCustomers endpoint. It includes details on parameters, responses, and required scopes.

```json
{
  "openapi": "3.0.1",
  "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": "API 2026-04",
    "version": "2026-04"
  },
  "servers": [
    {
      "url": "https://{domain_prefix}.retail.lightspeed.app/api/2026-04",
      "variables": {
        "domain_prefix": {
          "default": "example",
          "description": "Domain prefix of the store to be operated on"
        }
      }
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "externalDocs": {
    "description": "List of tz database time zones",
    "url": "https://en.wikipedia.org/wiki/List_of_tz_database_time_zones"
  },
  "tags": [
    {
      "description": "Customer operations",
      "name": "Customers"
    }
  ],
  "paths": {
    "/customers": {
      "get": {
        "description": "Returns a paginated list of customers.\n\nTo search for customers, please have a look at our [Search endpoint](/reference/search-1) on what is supported.\n\n🔒 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
                    }
                  ]
                }
              }
            }
          }
        }
      }
    }
  }
}
```

--------------------------------

### List Customers

Source: https://x-series-api.lightspeedhq.com/reference/listcustomers

Retrieves a list of customers. Supports filtering and pagination.

```APIDOC
## GET /customers

### Description
Retrieves a list of customers. Supports filtering and pagination.

### Method
GET

### Endpoint
/customers

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - The maximum number of records to return.
- **offset** (integer) - Optional - The number of records to skip before starting to collect the result set.
- **fields** (string) - Optional - A comma-separated list of fields to include in the response.
- **sort** (string) - Optional - The field to sort by. Use a hyphen prefix for descending order.
- **q** (string) - Optional - Search term to filter customers by name, email, or phone.

### Response
#### Success Response (200)
- **results** (array) - A list of customer objects.
  - **balance** (number) - Customer's unpaid balance.
  - **company_name** (string) - Company name.
  - **created_at** (string) - Creation timestamp in UTC.
  - **custom_field_1** (string) - Custom field 1. Can be used to store random data.
  - **custom_field_2** (string) - Custom field 2.
  - **custom_field_3** (string) - Custom field 3.
  - **custom_field_4** (string) - Custom field 4.
  - **customer_code** (string) - Customer code used for claiming loyalty.
  - **customer_group_id** (string) - Customer group ID.
  - **date_of_birth** (string) - Birthday.
  - **deleted_at** (string) - Deletion timestamp in UTC.
  - **do_not_email** (boolean) - Indicates whether the customer opted out of email communications.
  - **email** (string) - Customer's email address.
  - **enable_loyalty** (boolean) - Indicates if loyalty is enabled for the customer.
  - **enable_promotional_sms** (boolean) - Indicates whether the customer opted in to SMS communications.
  - **fax** (string) - Fax no.
  - **first_name** (string) - Customer's first name.
  - **gender** (string) - Customer's gender. Can be `M`, `F` or null.
  - **id** (string) - Auto-generated object ID.
  - **last_name** (string) - Customer's last name.
  - **loyalty_balance** (number) - Customer's loyalty balance.
  - **mobile** (string) - Mobile phone no.
  - **name** (string) - Customers full name. **deprecated**
  - **note** (string) - Customer note.
  - **on_account_limit** (number) - Customer's OnAccount Limit.
  - **updated_at** (string) - Last update timestamp in UTC.
  - **version** (integer) - Version number.
  - **year_to_date** (number) - Year to date balance.

#### Response Example
{
  "results": [
    {
      "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
    }
  ]
}
```

--------------------------------

### List Customers

Source: https://x-series-api.lightspeedhq.com/reference/listcustomers

Retrieves a paginated list of customers. Supports filtering by version numbers and page size, and can include deleted items. For searching capabilities, refer to the Search endpoint documentation.

```APIDOC
## GET /customers

### Description
Returns a paginated list of customers.

To search for customers, please have a look at our [Search endpoint](/reference/search-1) on what is supported.

🔒 Requires: `customers:read` scope

### Method
GET

### Endpoint
/customers

### Parameters
#### Query Parameters
- **after** (integer) - Optional - The lower limit for the version numbers to be included in the response.
- **before** (integer) - Optional - The upper limit for the version numbers to be included in the response.
- **page_size** (integer) - Optional - The maximum number of items to be returned in the response.
- **deleted** (boolean) - Optional - Indicates whether deleted items should be included in the response.

### Response
#### Success Response (200)
- **data** (array) - List of customer objects.
  - **balance** (number) - Current balance of the customer.
  - **company_name** (string) - The name of the company.
  - **created_at** (string) - Timestamp when the customer was created.
  - **custom_field_1** (string) - Value for custom field 1.
  - **custom_field_2** (string) - Value for custom field 2.
  - **custom_field_3** (string) - Value for custom field 3.
  - **custom_field_4** (string) - Value for custom field 4.
  - **customer_code** (string) - Unique code for the customer.
  - **customer_group_id** (string) - ID of the customer group.
  - **date_of_birth** (string) - Customer's date of birth.
  - **do_not_email** (boolean) - Flag to indicate if emails should not be sent.
  - **email** (string) - Customer's email address.
  - **enable_loyalty** (boolean) - Flag to enable loyalty program for the customer.
  - **enable_promotional_sms** (boolean) - Flag to enable promotional SMS for the customer.
  - **fax** (string) - Customer's fax number.
  - **first_name** (string) - Customer's first name.
  - **gender** (string) - Customer's gender.
  - **id** (string) - Unique identifier for the customer.
  - **last_name** (string) - Customer's last name.
  - **loyalty_balance** (number) - Current loyalty points balance.
  - **mobile** (string) - Customer's mobile number.
  - **name** (string) - Full name of the customer.
  - **note** (string) - Any notes associated with the customer.
  - **on_account_limit** (integer) - Credit limit for on-account purchases.
  - **phone** (string) - Customer's phone number.
  - **physical_address_1** (string) - First line of the physical address.
  - **physical_address_2** (string) - Second line of the physical address.
  - **physical_city** (string) - City of the physical address.
  - **physical_country_id** (string) - Country ID of the physical address.
  - **physical_postcode** (string) - Postcode of the physical address.
  - **physical_state** (string) - State of the physical address.
  - **physical_suburb** (string) - Suburb of the physical address.
  - **postal_address_1** (string) - First line of the postal address.
  - **postal_address_2** (string) - Second line of the postal address.
  - **postal_city** (string) - City of the postal address.
  - **postal_country_id** (string) - Country ID of the postal address.
  - **postal_postcode** (string) - Postcode of the postal address.
  - **postal_state** (string) - State of the postal address.
  - **postal_suburb** (string) - Suburb of the postal address.
  - **twitter** (string) - Customer's Twitter handle.
  - **updated_at** (string) - Timestamp when the customer was last updated.
  - **version** (integer) - Version number of the customer record.
  - **website** (string) - Customer's website URL.
  - **year_to_date** (number) - Year-to-date balance.

#### Response Example
```json
{
  "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
    }
  ]
}
```
```
Tokens:
Raw