---
search:
  tags:
    - Customers
    - GET
seo:
  description: >-
    Returns customers for a shop, or for a whole seller across all of its shops.
    Reference for the GET /customers endpoint in the Bolder API v2.
sidebar:
  label: List customers
  badge: GET
title: List customers
type: openapi-operation
---
Returns customers for a shop, or for a whole seller across all of its shops.

`shop_id` and `seller_id` are both optional. If the token covers exactly
one shop, that shop is auto-resolved and results are scoped to it. If the
token covers multiple shops belonging to a single seller, omitting both
params returns customers across all of that seller's shops. A token
covering multiple sellers (or a god token) must pass `shop_id` or
`seller_id` explicitly — there is no "all sellers" search.

`GET /customers`

**cURL**

```bash
# List all customers for a shop
curl -s -H "Authorization: Bearer $BOLDER_TOKEN" \
  "https://api.onbolder.com/v2/customers?shop_id=1"

# List customers across all of a seller's shops
curl -s -H "Authorization: Bearer $BOLDER_TOKEN" \
  "https://api.onbolder.com/v2/customers?seller_id=1"

# Search by name or email
curl -s -H "Authorization: Bearer $BOLDER_TOKEN" \
  "https://api.onbolder.com/v2/customers?shop_id=1&q=jane"
```

**Responses**

- `200` — Paginated list of contacts
- `403` — Access denied
- `422` — \`shop\_id\` or \`seller\_id\` required — the token covers more than one shop and more than one seller (or is a god token), so neither can be auto-resolved.

Response example, 200:

```json
{
  "_class": [
    "results",
    "customers"
  ],
  "total_items": 1,
  "per_page": 20,
  "page": 1,
  "_links": {
    "self": {
      "href": "https://api.onbolder.com/v2/customers?shop_id=1"
    },
    "customers:authenticate": {
      "href": "https://api.onbolder.com/v2/customers/sessions",
      "method": "post"
    },
    "customers:reset_password": {
      "href": "https://api.onbolder.com/v2/customers/reset_password",
      "method": "post"
    }
  },
  "_embedded": {
    "items": [
      {
        "id": 3001,
        "shop_id": 1,
        "email": "jane@example.com",
        "name": "Jane Smith",
        "customer_status": "private",
        "phone_validated": false,
        "created_on": "2024-03-10T11:00:00Z",
        "_links": {
          "self": {
            "href": "https://api.onbolder.com/v2/customers/3001"
          },
          "orders": {
            "href": "https://api.onbolder.com/v2/orders?shop_id=1&contact_email=jane@example.com"
          }
        }
      }
    ]
  }
}
```