Customers API

Required scope: customers:read (read) · customers:write (write)

---

List Customers

GET /api/v1/customers

Returns a paginated list of customers.

Query Parameters

Parameter	Type	Description
page	integer	Page number (default: 1)
per_page	integer	Results per page (default: 25, max: 100)
q	string	Search by name, email, phone, or customer code
updated_since	ISO 8601	Only return customers updated after this timestamp

Response

{
  "data": [
    {
      "id": 1,
      "name": "Jane Smith",
      "email": "jane@example.com",
      "phone": "5551234567",
      "customer_code": "C10001",
      "loyalty_card_number": "LC-0001",
      "loyalty_tier": "Gold",
      "loyalty_points": 2450,
      "lifetime_spend": 1250.00,
      "visit_count": 34,
      "store_credit_balance": 15.00,
      "address": {
        "line1": "123 Main St",
        "city": "Saskatoon",
        "province": "SK",
        "postal_code": "S7K 1A1",
        "country": "CA"
      },
      "created_at": "2025-06-10T08:00:00Z",
      "updated_at": "2026-03-21T16:45:00Z"
    }
  ],
  "pagination": { ... }
}

---

Get a Customer

GET /api/v1/customers/:id

---

Create a Customer

POST /api/v1/customers

Required scope: customers:write

Request Body

{
  "customer": {
    "name": "John Doe",
    "email": "john@example.com",
    "phone": "5559876543",
    "loyalty_card_number": "LC-0042"
  }
}

---

Update a Customer

PATCH /api/v1/customers/:id

Required scope: customers:write

Request Body

{
  "customer": {
    "email": "newemail@example.com",
    "phone": "5551111111"
  }
}