> ## Documentation Index > Fetch the complete documentation index at: https://docs.headlesscommerce.io/llms.txt > Use this file to discover all available pages before exploring further. # List Customers ## OpenAPI ````yaml openapi.yaml get /admin/customers openapi: 3.1.0 info: title: Headless Commerce API description: > Headless Commerce as a Service — REST API specification. ## Authentication Pass your API key as a Bearer token in every request. - **Secret Key** (`sk_live_*`, `sk_test_*`): Server-side. Full access to Admin + Storefront APIs. - **Publishable Key** (`pk_live_*`, `pk_test_*`): Client-side. Storefront API only. ## Customer Authentication (Storefront) Storefront endpoints that require customer identification (/storefront/customers/*, /storefront/orders/*) need the `X-Customer-Token` header. 1. From your backend, call `POST /admin/customers/{id}/token` with an `sk_*` key to issue a token 2. From the frontend, send requests with the `pk_*` key + `X-Customer-Token` header ## Pagination Uses cursor-based pagination. - `limit`: Page size (default 20, max 100) - `starting_after`: Return results after this ID - Response includes `has_more` and `next_cursor` ## Money All amounts are integers in the smallest currency unit (KRW=won, USD=cents). ## Rate Limiting All responses include the following headers: - `X-RateLimit-Limit`: Max requests per minute (by plan: Free 100, Starter 500, Pro 2000, Enterprise 10000) - `X-RateLimit-Remaining`: Remaining requests in current window - Returns `429 Too Many Requests` when exceeded ## Idempotency Include an `Idempotency-Key` header with payment/order-related POST requests to receive the original response for duplicate requests with the same key. Recommended for: checkout, refund, and payment creation version: 1.0.0 contact: name: Headless Commerce Support url: https://headlesscommerce.io servers: - url: https://api.headlesscommerce.io/v1 description: Production - url: https://api.headlesscommerce.io/v1 description: Test (same URL, test API key) security: - BearerAuth: [] tags: - name: Storefront - Products description: Browse products for buyers - name: Storefront - Cart description: Cart management and checkout - name: Storefront - Orders description: View orders (own orders) - name: Storefront - Customers description: Customer profile (own profile) - name: Storefront - Shipping description: View shipping methods - name: Admin - Products description: Product management - name: Admin - Variants description: Variant management - name: Admin - Categories description: Category management - name: Admin - Collections description: Collection management - name: Admin - Inventory description: Inventory management - name: Admin - Orders description: Order management - name: Admin - Fulfillments description: Fulfillment management - name: Admin - Customers description: Customer management - name: Admin - Discounts description: Discount management - name: Admin - Shipping Methods description: Shipping method management - name: Admin - Webhooks description: Webhook management - name: Admin - Store description: Store settings - name: Admin - Settings description: API keys, organization, and team management - name: Admin - Returns description: Return management - name: Admin - Regions description: Region, i18n, and currency rate management - name: Admin - Dashboard description: Dashboard statistics - name: Admin - Logs description: API log viewing - name: Admin - Uploads description: File uploads - name: Storefront - Returns description: Customer return requests and viewing - name: Storefront - Customer Auth description: Customer registration and login - name: Storefront - Payments description: Payment confirmation - name: OAuth description: OAuth 2.1 Authorization Code flow with PKCE - name: Auth description: Dashboard user password reset - name: Admin - CSV description: Bulk CSV import and export paths: /admin/customers: get: tags: - Admin - Customers summary: List Customers parameters: - $ref: '#/components/parameters/Limit' - $ref: '#/components/parameters/StartingAfter' - name: q in: query schema: type: string description: Search by name/email responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/CustomerListResponse' components: parameters: Limit: name: limit in: query schema: type: integer minimum: 1 maximum: 100 default: 20 StartingAfter: name: starting_after in: query schema: type: string description: Return results after this ID (cursor) schemas: CustomerListResponse: type: object properties: data: type: array items: $ref: '#/components/schemas/Customer' total_count: type: integer description: Only returned in Admin API has_more: type: boolean next_cursor: type: string nullable: true Customer: type: object properties: id: type: string email: type: string first_name: type: string last_name: type: string phone: type: string external_id: type: string status: type: string enum: - active - disabled total_orders: type: integer total_spent: $ref: '#/components/schemas/Money' tags: type: array items: type: string addresses: type: array items: $ref: '#/components/schemas/Address' metadata: type: object created_at: type: string format: date-time Money: type: object required: - amount - currency properties: amount: type: integer description: Smallest currency unit (KRW=won, USD=cents) currency: type: string minLength: 3 maxLength: 3 Address: type: object properties: name: type: string company: type: string line1: type: string line2: type: string city: type: string state: type: string postal_code: type: string country: type: string description: ISO 3166-1 alpha-2 phone: type: string securitySchemes: BearerAuth: type: http scheme: bearer description: 'API Key. Example: sk_live_xxxxx or pk_live_xxxxx' ````