Lightspeed Commerce

Lightspeed Commerce Customer Addresses API

Customer Address operations

Documentation GitHub OpenAPI

Business capability

Customer Data Management BC-420.10

Operations 5

GET /customers/{customer_id}/addresses List all addresses for a customer #

POST /customers/{customer_id}/addresses Create a new address for a customer #

DELETE /customers/{customer_id}/addresses/{address_id} Delete an address #

GET /customers/{customer_id}/addresses/{address_id} Get a single address #

PUT /customers/{customer_id}/addresses/{address_id} Update an address #

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-customer-addresses-api"

All apis

curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no email required.

GitHub Google LinkedIn

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

OpenAPI Specification

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 Customer Addresses 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 Address operations
  name: Customer Addresses
paths:
  /customers/{customer_id}/addresses:
    get:
      description: 'Returns a list of all addresses associated with the specified customer.


        🔒 Requires: `customers:read` scope'
      operationId: ListCustomerAddresses
      parameters:
      - description: The unique identifier of the customer.
        in: path
        name: customer_id
        required: true
        schema:
          format: uuid
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                - address_line_1: 123 Main Street
                  address_line_2: Suite 100
                  city: Auckland
                  country_code: NZ
                  country_name: New Zealand
                  created_at: '2025-01-12T10:00:00Z'
                  customer_id: b8ca3a65-0183-11e4-fbb5-4f73f02a9d1c
                  id: 123456789
                  postcode: '1010'
                  state: Auckland
                  state_code: AUK
                  suburb: Downtown
                  type: BILLING
                  updated_at: '2025-01-12T10:00:00Z'
              schema:
                $ref: '#/components/schemas/CustomerAddressCollection'
          description: ''
        '401':
          description: Unauthorized
        '403':
          description: Forbidden - insufficient permissions
        '404':
          description: Customer not found
      summary: List all addresses for a customer
      tags:
      - Customer Addresses
    post:
      description: 'Creates a new address for the specified customer.


        **Validation Rules:**

        - `country_code`: Required, must be a valid ISO 3166-1 alpha-2 code (e.g., US, NZ, AU)

        - `state_code`: Required for US and CA, must be valid for the country

        - `postcode`: Required, must be valid format for the country

        - `type`: Required, must be either BILLING or SHIPPING

        - `address_line_1`: Required, maximum 50 characters

        - `city`: Required, maximum 28 characters

        - `state`: Maximum 35 characters


        🔒 Requires: `customers:write` scope'
      operationId: CreateCustomerAddress
      parameters:
      - description: The unique identifier of the customer.
        in: path
        name: customer_id
        required: true
        schema:
          format: uuid
          type: string
      requestBody:
        content:
          application/json:
            example:
              address_line_1: 123 Main Street
              address_line_2: Suite 100
              city: Auckland
              country_code: NZ
              postcode: '1010'
              state: Auckland
              state_code: AUK
              suburb: Downtown
              type: BILLING
            schema:
              $ref: '#/components/schemas/CustomerAddressBase'
        required: true
      responses:
        '201':
          content:
            application/json:
              example:
                data:
                  address_line_1: 123 Main Street
                  address_line_2: Suite 100
                  city: Auckland
                  country_code: NZ
                  country_name: New Zealand
                  created_at: '2025-01-12T10:00:00Z'
                  customer_id: b8ca3a65-0183-11e4-fbb5-4f73f02a9d1c
                  id: 123456789
                  id_token: abc123token
                  postcode: '1010'
                  state: Auckland
                  state_code: AUK
                  suburb: Downtown
                  type: BILLING
                  updated_at: '2025-01-12T10:00:00Z'
              schema:
                $ref: '#/components/schemas/CustomerAddressCreateResponse'
          description: Address created successfully
        '400':
          description: Bad Request - validation errors
        '401':
          description: Unauthorized
        '403':
          description: Forbidden - insufficient permissions
        '404':
          description: Customer not found
      summary: Create a new address for a customer
      tags:
      - Customer Addresses
      x-codegen-request-body-name: body
  /customers/{customer_id}/addresses/{address_id}:
    delete:
      description: 'Deletes an address for the specified customer.


        🔒 Requires: `customers:write` scope'
      operationId: DeleteCustomerAddress
      parameters:
      - description: The unique identifier of the customer.
        in: path
        name: customer_id
        required: true
        schema:
          format: uuid
          type: string
      - description: The unique identifier of the address.
        in: path
        name: address_id
        required: true
        schema:
          format: int64
          type: integer
      responses:
        '204':
          description: Address deleted successfully
        '401':
          description: Unauthorized
        '403':
          description: Forbidden - insufficient permissions or address is read-only
        '404':
          description: Customer or address not found
      summary: Delete an address
      tags:
      - Customer Addresses
    get:
      description: 'Returns a single address by its ID for the specified customer.


        🔒 Requires: `customers:read` scope'
      operationId: GetCustomerAddress
      parameters:
      - description: The unique identifier of the customer.
        in: path
        name: customer_id
        required: true
        schema:
          format: uuid
          type: string
      - description: The unique identifier of the address.
        in: path
        name: address_id
        required: true
        schema:
          format: int64
          type: integer
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  address_line_1: 123 Main Street
                  address_line_2: Suite 100
                  city: Auckland
                  country_code: NZ
                  country_name: New Zealand
                  created_at: '2025-01-12T10:00:00Z'
                  customer_id: b8ca3a65-0183-11e4-fbb5-4f73f02a9d1c
                  id: 123456789
                  postcode: '1010'
                  state: Auckland
                  state_code: AUK
                  suburb: Downtown
                  type: BILLING
                  updated_at: '2025-01-12T10:00:00Z'
              schema:
                $ref: '#/components/schemas/CustomerAddressResponse'
          description: ''
        '401':
          description: Unauthorized
        '403':
          description: Forbidden - insufficient permissions
        '404':
          description: Customer or address not found
      summary: Get a single address
      tags:
      - Customer Addresses
    put:
      description: 'Updates an existing address for the specified customer.


        **Validation Rules:**

        - `country_code`: Required, must be a valid ISO 3166-1 alpha-2 code (e.g., US, NZ, AU)

        - `state_code`: Required for US and CA, must be valid for the country

        - `postcode`: Required, must be valid format for the country

        - `type`: Required, must be either BILLING or SHIPPING

        - `address_line_1`: Required, maximum 50 characters

        - `city`: Required, maximum 28 characters

        - `state`: Maximum 35 characters


        🔒 Requires: `customers:write` scope'
      operationId: UpdateCustomerAddress
      parameters:
      - description: The unique identifier of the customer.
        in: path
        name: customer_id
        required: true
        schema:
          format: uuid
          type: string
      - description: The unique identifier of the address.
        in: path
        name: address_id
        required: true
        schema:
          format: int64
          type: integer
      requestBody:
        content:
          application/json:
            example:
              address_line_1: 456 Updated Avenue
              address_line_2: Floor 2
              city: Wellington
              country_code: NZ
              postcode: '6011'
              state: Wellington
              state_code: WGN
              suburb: Midtown
              type: SHIPPING
            schema:
              $ref: '#/components/schemas/CustomerAddressBase'
        required: true
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  address_line_1: 456 Updated Avenue
                  address_line_2: Floor 2
                  city: Wellington
                  country_code: NZ
                  country_name: New Zealand
                  created_at: '2025-01-12T10:00:00Z'
                  customer_id: b8ca3a65-0183-11e4-fbb5-4f73f02a9d1c
                  id: 123456789
                  postcode: '6011'
                  state: Wellington
                  state_code: WGN
                  suburb: Midtown
                  type: SHIPPING
                  updated_at: '2025-01-12T12:30:00Z'
              schema:
                $ref: '#/components/schemas/CustomerAddressResponse'
          description: Address updated successfully
        '400':
          description: Bad Request - validation errors
        '401':
          description: Unauthorized
        '403':
          description: Forbidden - insufficient permissions or address is read-only
        '404':
          description: Customer or address not found
      summary: Update an address
      tags:
      - Customer Addresses
      x-codegen-request-body-name: body
components:
  schemas:
    CustomerAddressResponse:
      properties:
        data:
          $ref: '#/components/schemas/CustomerAddress'
      title: Customer Address Response
      type: object
    CustomerAddressCreateResponse:
      properties:
        data:
          allOf:
          - $ref: '#/components/schemas/CustomerAddress'
          - properties:
              id_token:
                description: Token to be used when associating this address with a sale.
                type: string
            type: object
      title: Customer Address Create Response
      type: object
    CustomerAddressCollection:
      properties:
        data:
          description: An array of customer address objects.
          items:
            $ref: '#/components/schemas/CustomerAddress'
          type: array
      title: Customer Address Collection
      type: object
    CustomerAddress:
      properties:
        address_line_1:
          description: Primary address line (street address, P.O. box, etc.).
          maxLength: 50
          type: string
        address_line_2:
          description: Secondary address line (apartment, suite, unit, building, floor, etc.).
          maxLength: 50
          type:
          - string
          - 'null'
        city:
          description: City or town name.
          maxLength: 28
          type: string
        country_code:
          description: ISO 3166-1 alpha-2 country code (e.g., US, NZ, AU).
          type: string
        country_name:
          description: Full country name derived from the country code.
          type: string
        created_at:
          description: Creation timestamp in UTC.
          format: date-time
          type: string
        customer_id:
          description: The unique identifier of the customer this address belongs to.
          format: uuid
          type: string
        id:
          description: Auto-generated address ID.
          format: int64
          type: integer
        postcode:
          description: Postal code or ZIP code.
          type: string
        state:
          description: State, province, or region name.
          maxLength: 35
          type:
          - string
          - 'null'
        state_code:
          description: State or province code. Required for US and CA.
          type:
          - string
          - 'null'
        suburb:
          description: Suburb or district.
          type:
          - string
          - 'null'
        type:
          description: The type of address.
          enum:
          - BILLING
          - SHIPPING
          type: string
        updated_at:
          description: Last update timestamp in UTC.
          format: date-time
          type: string
      required:
      - id
      - customer_id
      - address_line_1
      - city
      - postcode
      - country_code
      - type
      - created_at
      - updated_at
      title: Customer Address
      type: object
    CustomerAddressBase:
      properties:
        address_line_1:
          description: Primary address line (street address, P.O. box, etc.).
          maxLength: 50
          type: string
        address_line_2:
          description: Secondary address line (apartment, suite, unit, building, floor, etc.).
          maxLength: 50
          type:
          - string
          - 'null'
        city:
          description: City or town name.
          maxLength: 28
          type: string
        country_code:
          description: ISO 3166-1 alpha-2 country code (e.g., US, NZ, AU).
          type: string
        postcode:
          description: Postal code or ZIP code.
          type: string
        state:
          description: State, province, or region name.
          maxLength: 35
          type:
          - string
          - 'null'
        state_code:
          description: State or province code. Required for US and CA.
          type:
          - string
          - 'null'
        suburb:
          description: Suburb or district.
          type:
          - string
          - 'null'
        type:
          description: The type of address.
          enum:
          - BILLING
          - SHIPPING
          type: string
      required:
      - address_line_1
      - city
      - postcode
      - country_code
      - type
      title: Customer Address 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