> ## Documentation Index
> Fetch the complete documentation index at: https://www.commercengine.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# List all customers



## OpenAPI

````yaml https://openapi.commercengine.io/ce-pos.json get /pos/customers
openapi: 3.2.0
info:
  title: CE POS APIs
  description: >-
    The consolidated Point of Sale surface. Every operation is served under the
    storefront base URL; the POS backend proxies some of them to the admin
    service.
  version: '1.0'
servers:
  - url: https://staging.api.commercengine.io/api/v1/{store_id}/storefront
    description: Staging Server
    variables:
      store_id:
        description: Store ID
        default: store_id
    x-speakeasy-server-id: staging
  - url: https://prod.api.commercengine.io/api/v1/{store_id}/storefront
    description: Prod Server
    variables:
      store_id:
        description: Store ID
        default: store_id
    x-speakeasy-server-id: prod
security:
  - Authorization: []
tags:
  - name: section-identity
    summary: Identity
    kind: nav
  - name: Devices
    description: >-
      Set up the till: pair a device with the store using its pairing code, list
      the store's `PosLocation`s and `PosDevice`s, and claim a device for the
      signed-in user or release it.
    summary: Devices
    kind: nav
    parent: section-identity
  - name: Authentication
    description: >-
      Sign a staff member in on a paired device with a one-time password over
      SMS, WhatsApp or email, then refresh the access token or log out.
    summary: Authentication
    kind: nav
    parent: section-identity
  - name: Users
    description: >-
      The staff member signed in on the till, as a `PosUser` with their
      location, device and roles.
    summary: Users
    kind: nav
    parent: section-identity
  - name: section-customers
    summary: Customers
    kind: nav
  - name: Customers
    description: >-
      Look up the shopper at the till: list customers (`CustomerListItem`) and
      read one's full `CustomerDetail`.
    summary: Customers
    kind: nav
    parent: section-customers
  - name: Addresses
    description: >-
      A customer's saved addresses, as `Address` objects: list, add, update and
      remove them.
    summary: Addresses
    kind: nav
    parent: section-customers
  - name: section-catalog
    summary: Catalog
    kind: nav
  - name: Products
    description: >-
      Browse and search the catalog at the till: list `Product`s and SKUs, read
      a product and its variants, and show similar, up-sell and cross-sell
      items.
    summary: Products
    kind: nav
    parent: section-catalog
  - name: Reviews
    description: Read product reviews at the till.
    summary: Reviews
    kind: nav
    parent: section-catalog
  - name: Categories
    description: >-
      The store's categories, as `ProductCategory` objects with their child
      categories.
    summary: Categories
    kind: nav
    parent: section-catalog
  - name: Inventory
    description: >-
      Stock at the store's locations: list it by item, read an item's
      `InventoryDetail`, and follow the `InventoryActivity` that moved it.
    summary: Inventory
    kind: nav
    parent: section-catalog
  - name: section-shopping
    summary: Shopping
    kind: nav
  - name: Carts
    description: >-
      The till's `Cart`: create it, add, update or remove items, link the
      customer, set the address, and apply loyalty points or credit balance.
      Each update returns the full, updated `Cart`.
    summary: Carts
    kind: nav
    parent: section-shopping
  - name: Coupons & promotions
    description: >-
      The coupons and promotions a cart can use: list what the store offers, see
      which apply to a cart and why the rest don't, and apply or remove a
      coupon.
    summary: Coupons & promotions
    kind: nav
    parent: section-shopping
  - name: Fulfillment
    description: >-
      List the delivery and collect-in-store options for a cart, and save the
      cart's choice.
    summary: Fulfillment
    kind: nav
    parent: section-shopping
  - name: section-orders
    summary: Orders
    kind: nav
  - name: Orders
    description: >-
      Place an order from the till's cart and follow it: list orders, read an
      `OrderDetail` and its activity, check stock before it ships, and get its
      invoice, receipt and shipments.
    summary: Orders
    kind: nav
    parent: section-orders
  - name: Order payments
    description: >-
      Collect payment for an order: add payments toward what is left to pay,
      across one or more methods, poll the payment status, and retry a failed or
      expired payment.
    summary: Order payments
    kind: nav
    parent: section-orders
  - name: Shipments
    description: >-
      The shipments that fulfill orders: list them, read a `ShipmentDetail` with
      its activity and invoice, approve, reject or update one, send a
      replacement, and refund a shortfall.
    summary: Shipments
    kind: nav
    parent: section-orders
  - name: section-payments
    summary: Payments
    kind: nav
  - name: Payments
    description: >-
      The payment methods the till accepts and the checks around paying with
      them: card BIN details, VPA verification, and authenticating a payment
      with a direct OTP.
    summary: Payments
    kind: nav
    parent: section-payments
  - name: section-store
    summary: Store
    kind: nav
  - name: Locations
    description: States and pincodes for address forms.
    summary: Locations
    kind: nav
    parent: section-store
paths:
  /pos/customers:
    get:
      tags:
        - Customers
      summary: List all customers
      operationId: pos-list-customers
      parameters:
        - $ref: '#/components/parameters/pageNumber'
        - $ref: '#/components/parameters/pageLimit'
        - $ref: '#/components/parameters/columnBasedFilters'
        - $ref: '#/components/parameters/sortByOptions'
        - $ref: '#/components/parameters/searchKeyword'
        - name: business_name
          in: query
          description: Filter by business name.
          required: false
          schema:
            type: string
        - name: business_type
          in: query
          description: Filter by business type.
          required: false
          schema:
            type: string
        - name: contact_email
          in: query
          description: Filter by contact email.
          required: false
          schema:
            type: string
        - name: contact_phone
          in: query
          description: Filter by contact phone.
          required: false
          schema:
            type: string
        - name: created_at
          in: query
          description: Filter by created at.
          required: false
          schema:
            type: string
        - name: customer_email
          in: query
          description: Filter by customer email.
          required: false
          schema:
            type: string
        - name: customer_group_id
          in: query
          description: Filter by customer group id.
          required: false
          schema:
            type: string
        - name: customer_phone
          in: query
          description: Filter by customer phone.
          required: false
          schema:
            type: string
        - name: gstin
          in: query
          description: Filter by gstin.
          required: false
          schema:
            type: string
        - name: inbound_bank_account_id
          in: query
          description: Filter by inbound bank account id.
          required: false
          schema:
            type: integer
        - name: is_email_verified
          in: query
          description: Filter by is email verified.
          required: false
          schema:
            type: boolean
        - name: is_phone_verified
          in: query
          description: Filter by is phone verified.
          required: false
          schema:
            type: boolean
        - name: is_registered_under_gst
          in: query
          description: Filter by is registered under gst.
          required: false
          schema:
            type: boolean
        - name: is_verified
          in: query
          description: Filter by is verified.
          required: false
          schema:
            type: boolean
        - name: is_whatsapp_verified
          in: query
          description: Filter by is whatsapp verified.
          required: false
          schema:
            type: boolean
        - name: kyc_status
          in: query
          description: Filter by kyc status.
          required: false
          schema:
            type: string
        - name: metadata
          in: query
          description: Filter by metadata.
          required: false
          schema:
            type: string
        - name: modified_at
          in: query
          description: Filter by modified at.
          required: false
          schema:
            type: string
        - name: outbound_bank_account_id
          in: query
          description: Filter by outbound bank account id.
          required: false
          schema:
            type: integer
        - name: pan_number
          in: query
          description: Filter by pan number.
          required: false
          schema:
            type: string
        - name: primary_address_id
          in: query
          description: Filter by primary address id.
          required: false
          schema:
            type: integer
        - name: store_id
          in: query
          description: Filter by store id.
          required: false
          schema:
            type: string
        - name: tags
          in: query
          description: Filter by tags.
          required: false
          schema:
            type: string
        - name: tax_identification_number
          in: query
          description: Filter by tax identification number.
          required: false
          schema:
            type: string
        - name: ulid
          in: query
          description: Filter by one or more customer IDs, separated by commas.
          required: false
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                  - success
                  - content
                properties:
                  message:
                    type: string
                  success:
                    type: boolean
                  content:
                    properties:
                      customers:
                        type: array
                        items:
                          $ref: '#/components/schemas/CustomerListItem'
                      pagination:
                        $ref: '#/components/schemas/AdminPagination'
                    required:
                      - customers
                      - pagination
                    type: object
        '400':
          $ref: '#/components/responses/AdminBadRequest'
        '401':
          $ref: '#/components/responses/AdminUnauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/AdminInternalServerError'
        '504':
          $ref: '#/components/responses/GatewayTimeout'
      security:
        - Authorization: []
      externalDocs:
        url: >-
          https://llm-docs.commercengine.io/admin-pos/operations/pos-list-customers
components:
  parameters:
    pageNumber:
      name: page
      in: query
      required: false
      schema:
        type: integer
        default: 1
        minimum: 1
      description: >-
        Page number, starting at 1. Non-integer values and values below 1 return
        400.
    pageLimit:
      name: limit
      in: query
      required: false
      schema:
        type: integer
        default: 25
        maximum: 100
        minimum: 1
      description: >-
        Results per page. Values outside 1–100 are clamped to that range.
        Non-integer input returns 400.
    columnBasedFilters:
      name: filters
      in: query
      required: false
      schema:
        type: string
        example: >-
          {"condition":"AND","filters":[{"type":"data","field":"status","operator":"equals","value":"success"}]}
      description: JSON object
    sortByOptions:
      name: sort_by
      in: query
      required: false
      schema:
        description: >-
          json string in format {'field_name':'asc', 'other_field_name':'desc',
          ...}
        type: string
      description: 'JSON string format: {"field1":"asc", "field2":"desc"}'
    searchKeyword:
      name: search
      in: query
      description: search keyword
      required: false
      schema:
        type: string
  schemas:
    CustomerListItem:
      title: CustomerListItem
      externalDocs:
        url: https://llm-docs.commercengine.io/admin-pos/schemas/CustomerListItem
      allOf:
        - $ref: '#/components/schemas/Customer'
        - type: object
          properties:
            user_id:
              type: string
              readOnly: true
            metadata:
              description: Arbitrary key-value data stored against the customer.
              type:
                - object
                - 'null'
              additionalProperties: true
            address:
              description: A single address for the customer, `null` when none is saved.
              oneOf:
                - type: 'null'
                - $ref: '#/components/schemas/SavedCustomerAddress'
          required:
            - metadata
            - address
      x-tags:
        - Customers
    AdminPagination:
      title: Pagination
      description: pagination metadata structure
      type: object
      externalDocs:
        url: https://llm-docs.commercengine.io/admin-pos/schemas/AdminPagination
      required:
        - total_records
        - total_pages
        - previous_page
        - limit
        - next_page
      properties:
        total_records:
          type: integer
        total_pages:
          type: integer
        previous_page:
          description: Previous page number
          type:
            - integer
            - 'null'
        limit:
          type: integer
          default: 25
        next_page:
          description: Next page number
          type:
            - integer
            - 'null'
    Customer:
      title: Customer
      externalDocs:
        url: https://llm-docs.commercengine.io/admin-pos/schemas/Customer
      allOf:
        - $ref: '#/components/schemas/CustomerInfo'
        - type: object
          properties:
            business:
              description: >-
                Stored business fields are returned whenever a customer record
                exists, including when name is null or empty and when all
                optional fields are empty. business_type may contain a
                legacy/default customer group name; this object does not imply
                business registration. null is retained for representations
                without a linked customer record.
              oneOf:
                - type: 'null'
                - $ref: '#/components/schemas/BusinessInfo'
            segments:
              type: array
              items:
                $ref: '#/components/schemas/CustomerSegment'
            address:
              description: >-
                The customer's primary address. `null` when the customer has
                none.
              oneOf:
                - type: 'null'
                - $ref: '#/components/schemas/CustomerAddress'
          required:
            - business
            - segments
            - address
      x-tags:
        - Customers
    SavedCustomerAddress:
      title: SavedCustomerAddress
      type: object
      externalDocs:
        url: >-
          https://llm-docs.commercengine.io/admin-pos/schemas/SavedCustomerAddress
      required:
        - first_name
        - phone
        - email
        - address_line1
        - pincode
        - city
        - state
        - country
        - id
        - last_name
        - country_code
        - address_line2
        - landmark
        - gstin
        - business_name
        - is_phone_verified
        - is_email_verified
        - is_default_shipping
        - is_default_billing
        - created_at
        - modified_at
        - is_primary
      properties:
        id:
          type: string
          readOnly: true
        first_name:
          type:
            - string
            - 'null'
        last_name:
          type:
            - string
            - 'null'
        country_code:
          description: "Two-letter code begin with a plus sign prefix that identifies different countries. By default it will be +91 if not provided.\r\n"
          type: string
        phone:
          description: 10 digit phone number without country code.
          type:
            - string
            - 'null'
        email:
          type:
            - string
            - 'null'
        address_line1:
          type:
            - string
            - 'null'
        address_line2:
          type:
            - string
            - 'null'
        landmark:
          type:
            - string
            - 'null'
        pincode:
          type:
            - string
            - 'null'
        city:
          type:
            - string
            - 'null'
        state:
          type:
            - string
            - 'null'
        country:
          description: Country name. `null` when the address was saved without one.
          type:
            - string
            - 'null'
        gstin:
          description: Use in shipping details only for third party.
          type:
            - string
            - 'null'
        business_name:
          description: Use in shipping details only for third party.
          type:
            - string
            - 'null'
        is_phone_verified:
          type: boolean
          readOnly: true
        is_email_verified:
          type: boolean
          readOnly: true
        is_default_shipping:
          type: boolean
        is_default_billing:
          type: boolean
        created_at:
          type: string
          format: date-time
          readOnly: true
        modified_at:
          type: string
          format: date-time
          readOnly: true
        is_primary:
          type: boolean
          readOnly: true
      examples: []
      x-tags:
        - Customers
    CustomerInfo:
      title: CustomerInfo
      type: object
      externalDocs:
        url: https://llm-docs.commercengine.io/admin-pos/schemas/CustomerInfo
      required:
        - id
        - is_phone_verified
        - is_email_verified
        - is_whatsapp_verified
        - is_verified
        - kyc_status
        - tags
        - customer_group_id
        - created_at
        - modified_at
        - last_seen
      properties:
        id:
          description: >-
            Customer ID. An imported customer can have a different primary user
            ID.
          type: string
          readOnly: true
        first_name:
          type:
            - string
            - 'null'
        last_name:
          type:
            - string
            - 'null'
        full_name:
          type:
            - string
            - 'null'
          readOnly: true
        profile_image_url:
          type:
            - string
            - 'null'
          readOnly: true
        country_code:
          type:
            - string
            - 'null'
        phone:
          type:
            - string
            - 'null'
        email:
          type:
            - string
            - 'null'
        is_phone_verified:
          type: boolean
          readOnly: true
        is_email_verified:
          type: boolean
          readOnly: true
        is_whatsapp_verified:
          type: boolean
          readOnly: true
        status:
          description: '`null` for customers with no status recorded.'
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/CustomerStatus'
        created_at:
          type: string
          format: date-time
          readOnly: true
        modified_at:
          type: string
          format: date-time
          readOnly: true
        last_seen:
          description: Empty string when the customer has no recorded activity yet.
          type:
            - string
            - 'null'
          readOnly: true
        kyc_status:
          $ref: '#/components/schemas/KycStatus'
        is_verified:
          type: boolean
          readOnly: true
        customer_group_id:
          description: >-
            The Customer Group the customer belongs to. Drives group-specific
            pricing and promotions.
          type:
            - string
            - 'null'
        tags:
          type:
            - array
            - 'null'
          items:
            type: string
      x-tags:
        - Customers
    BusinessInfo:
      title: BusinessInfo
      type: object
      externalDocs:
        url: https://llm-docs.commercengine.io/admin-pos/schemas/BusinessInfo
      properties:
        name:
          type:
            - string
            - 'null'
        business_type:
          description: >-
            Stored customer business type. Existing records may contain free
            text, including a default customer group name from storefront
            signup. Newly supplied values: sole_proprietorship, partnership,
            private_limited, public_limited, public_listed, state_owned,
            charity, individual, llp, other. A value here does not imply the
            customer is a registered business.
          type:
            - string
            - 'null'
        pan_number:
          type:
            - string
            - 'null'
        gstin:
          type:
            - string
            - 'null'
        is_registered_under_gst:
          type: boolean
      x-tags:
        - Customers
    CustomerSegment:
      title: CustomerSegment
      type: object
      externalDocs:
        url: https://llm-docs.commercengine.io/admin-pos/schemas/CustomerSegment
      properties:
        id:
          type: string
        name:
          type: string
      x-tags:
        - Customers
    CustomerAddress:
      title: CustomerAddress
      type: object
      externalDocs:
        url: https://llm-docs.commercengine.io/admin-pos/schemas/CustomerAddress
      required:
        - first_name
        - phone
        - email
        - address_line1
        - pincode
        - city
        - state
        - country
      properties:
        id:
          type: string
          readOnly: true
        first_name:
          type:
            - string
            - 'null'
        last_name:
          type:
            - string
            - 'null'
        country_code:
          description: "Two-letter code begin with a plus sign prefix that identifies different countries. By default it will be +91 if not provided.\r\n"
          type: string
        phone:
          description: 10 digit phone number without country code.
          type:
            - string
            - 'null'
        email:
          type:
            - string
            - 'null'
        address_line1:
          type:
            - string
            - 'null'
        address_line2:
          type:
            - string
            - 'null'
        landmark:
          type:
            - string
            - 'null'
        pincode:
          type:
            - string
            - 'null'
        city:
          type:
            - string
            - 'null'
        state:
          type:
            - string
            - 'null'
        country:
          description: Country name. `null` when the address was saved without one.
          type:
            - string
            - 'null'
        gstin:
          description: Use in shipping details only for third party.
          type:
            - string
            - 'null'
        business_name:
          description: Use in shipping details only for third party.
          type:
            - string
            - 'null'
        is_phone_verified:
          type: boolean
          readOnly: true
        is_email_verified:
          type: boolean
          readOnly: true
        is_default_shipping:
          type: boolean
        is_default_billing:
          type: boolean
        created_at:
          type: string
          format: date-time
          readOnly: true
        modified_at:
          type: string
          format: date-time
          readOnly: true
        is_primary:
          type: boolean
          readOnly: true
      examples: []
      x-tags:
        - Customers
    CustomerStatus:
      title: CustomerStatus
      type: string
      externalDocs:
        url: https://llm-docs.commercengine.io/admin-pos/schemas/CustomerStatus
      examples:
        - active
        - inactive
    KycStatus:
      description: >-
        KYC progress for a customer. `document_pending` means required documents
        have not been uploaded; `submitted` and `submitted_for_approval` mean
        they are awaiting review.
      externalDocs:
        url: https://llm-docs.commercengine.io/admin-pos/schemas/KycStatus
      enum:
        - pending
        - document_pending
        - submitted
        - submitted_for_approval
        - approved
        - rejected
  responses:
    AdminBadRequest:
      description: The request is invalid or cannot be completed in the current state.
      content:
        application/json:
          schema:
            type: object
            required:
              - message
              - success
            properties:
              message:
                type: string
              success:
                type: boolean
              code:
                type: string
              errors:
                description: Validation details as a field map, a bulk list or a string.
                anyOf:
                  - type: object
                    additionalProperties: true
                  - type: array
                  - type: string
              content:
                type: object
                additionalProperties: true
              details:
                type: string
    AdminUnauthorized:
      description: >-
        The token is missing, invalid or expired, or does not grant access to
        this store and operation.
      content:
        application/json:
          schema:
            type: object
            required:
              - message
              - success
            properties:
              message:
                type: string
              success:
                type: boolean
              code:
                type: string
              details:
                type: string
    Forbidden:
      description: >-
        Access denied. `token-required` requires an authenticated session;
        `permission-denied` means the caller cannot access this resource. On
        POS, `session-expired` requires signing in again.
      content:
        application/json:
          schema:
            type: object
            required:
              - code
              - message
              - success
            properties:
              code:
                type: string
              message:
                type: string
                x-speakeasy-error-message: true
              success:
                type: boolean
              details:
                type: string
    NotFound:
      description: Requested resource not found
      content:
        application/json:
          schema:
            type: object
            required:
              - message
              - success
              - code
            properties:
              message:
                type: string
                x-speakeasy-error-message: true
              success:
                type: boolean
              code:
                type: string
              details:
                type: string
    AdminInternalServerError:
      description: >-
        The request could not be completed. Quote error_id, when present, when
        contacting support.
      content:
        application/json:
          schema:
            type: object
            required:
              - message
              - success
            properties:
              message:
                type: string
              success:
                type: boolean
              code:
                type: string
              details:
                type: string
              error_id:
                type: string
    GatewayTimeout:
      description: The request timed out.
      content:
        application/json:
          schema:
            type: object
            required:
              - code
              - message
              - success
            properties:
              code:
                type: string
              message:
                type: string
                x-speakeasy-error-message: true
              success:
                type: boolean
              details:
                type: string
  securitySchemes:
    Authorization:
      type: http
      description: Access token
      scheme: bearer

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.