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

# List Customers

> Retrieve a list of customers

# List Customers

Returns a paginated list of customers for the store. Requires the `read_customers` scope.

## Request

```bash theme={null}
curl -X GET "https://api.launchmystore.io/api/v1/customers.json?limit=50&page=1" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

## Parameters

<ParamField query="page" type="integer" default="1">
  Page number for pagination
</ParamField>

<ParamField query="limit" type="integer" default="50">
  Number of items per page
</ParamField>

<ParamField query="email" type="string">
  Filter by exact email address
</ParamField>

## Response

The response is a bare object keyed by `customers` containing an array of customer objects. Pagination is conveyed via the standard `Link` response header (`rel="next"` / `rel="previous"`) rather than a body field.

<ResponseField name="customers" type="array">
  Array of customer objects

  <Expandable title="Customer Object">
    <ResponseField name="id" type="string">
      Unique customer ID
    </ResponseField>

    <ResponseField name="email" type="string">
      Customer email
    </ResponseField>

    <ResponseField name="first_name" type="string">
      First name (derived from the stored full name)
    </ResponseField>

    <ResponseField name="last_name" type="string">
      Last name (derived from the stored full name)
    </ResponseField>

    <ResponseField name="name" type="string">
      Full name
    </ResponseField>

    <ResponseField name="phone" type="string">
      Phone number
    </ResponseField>

    <ResponseField name="accepts_marketing" type="boolean">
      Marketing opt-in status
    </ResponseField>

    <ResponseField name="orders_count" type="integer">
      Total number of orders
    </ResponseField>

    <ResponseField name="total_spent" type="string">
      Total amount spent, as a 2-decimal string (e.g. `"250.00"`)
    </ResponseField>

    <ResponseField name="tags" type="array">
      Customer tags. Always an empty array — customer tags are not stored.
    </ResponseField>

    <ResponseField name="addresses" type="array">
      Customer addresses. Empty for this endpoint — the list query does not load
      address records.
    </ResponseField>

    <ResponseField name="default_address" type="object">
      The default address, or `null`
    </ResponseField>

    <ResponseField name="created_at" type="string">
      Creation timestamp (ISO 8601)
    </ResponseField>

    <ResponseField name="updated_at" type="string">
      Last update timestamp (ISO 8601)
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="Link (response header)" type="string">
  RFC-5988 pagination links. Follow `rel="next"` until it is absent.
</ResponseField>

## Example Response

```json theme={null}
{
  "customers": [
    {
      "id": "cust_abc123",
      "email": "john.doe@example.com",
      "first_name": "John",
      "last_name": "Doe",
      "name": "John Doe",
      "phone": "+1-555-123-4567",
      "accepts_marketing": true,
      "orders_count": 5,
      "total_spent": "250.00",
      "tags": [],
      "addresses": [],
      "default_address": null,
      "created_at": "2023-06-15T10:30:00Z",
      "updated_at": "2024-01-20T14:45:00Z"
    }
  ]
}
```

## Errors

| Status | Description                                 |
| ------ | ------------------------------------------- |
| `401`  | Invalid or missing access token             |
| `403`  | App doesn't have the `read_customers` scope |