## List Customers

```
GET /api/v1/customers
```

Returns a paginated list of customers, sorted by creation date (newest first).

### Query Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `limit` | `number` | 50 | Customers per page (1-100) |
| `offset` | `number` | 0 | Customers to skip |
| `search` | `string` | – | Search by customer email |

### Response

```json
{
  "items": [
    {
      "id": "0191abc0-1234-7def-8000-000000000001",
      "email": "jane@example.com",
      "name": "Jane Doe",
      "createdAt": "2024-01-10T08:00:00.000Z"
    }
  ],
  "pagination": {
    "total": 156,
    "offset": 0,
    "limit": 50,
    "hasMore": true
  }
}
```

---

## Get Customer

```
GET /api/v1/customers/:id
```

Returns customer details including linked user info and all saved addresses.

```json
{
  "id": "0191abc0-1234-7def-8000-000000000001",
  "email": "jane@example.com",
  "name": "Jane Doe",
  "phone": null,
  "addresses": [
    {
      "id": "0191abc0-0000-7000-8000-000000000010",
      "line1": "123 Main St",
      "line2": null,
      "city": "San Francisco",
      "state": "CA",
      "postalCode": "94102",
      "country": "US",
      "name": "Jane Doe",
      "company": null,
      "phone": null
    }
  ],
  "createdAt": "2024-01-10T08:00:00.000Z"
}
```

---

## Update Customer

```
PATCH /api/v1/customers/:id
```

### Request Body

| Field | Type | Description |
|-------|------|-------------|
| `name` | `string` | Customer display name |
| `phone` | `string` | Customer phone number |

```bash
curl -X PATCH \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"name": "Jane Smith"}' \
  https://your-store.yns.store/api/v1/customers/0191abc0-1234-7def-8000-000000000001
```

---

## Customer Addresses

### Create Address

```
POST /api/v1/customers/:id/addresses
```

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `line1` | `string` | Yes | Street address line 1 |
| `line2` | `string` | No | Apartment, suite, etc. |
| `city` | `string` | Yes | City |
| `postalCode` | `string` | Yes | Postal/ZIP code |
| `country` | `string` | No | Two-letter country code (e.g. `US`) |
| `state` | `string` | No | State or province |
| `name` | `string` | No | Recipient full name |
| `company` | `string` | No | Company name |
| `phone` | `string` | No | Contact phone number |

```bash
curl -X POST \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "line1": "456 Oak Ave",
    "city": "Los Angeles",
    "state": "CA",
    "postalCode": "90001",
    "country": "US",
    "name": "Jane Doe"
  }' \
  https://your-store.yns.store/api/v1/customers/0191abc0-1234-7def-8000-000000000001/addresses
```

### Delete Address

```
DELETE /api/v1/customers/:id/addresses/:addressId
```

Removes an address from the customer's address book.

---

## Customer Orders

```
GET /api/v1/customers/:id/orders
```

Returns orders placed by this customer, paginated. See [Orders API](/docs/api-reference/orders) for response details.

### Query Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `limit` | `number` | 20 | Orders per page (1-100) |
| `offset` | `number` | 0 | Orders to skip |

### Response

```json
{
  "items": [
    {
      "id": "0191abc0-1234-7def-8000-000000000001",
      "orderNumber": "1042",
      "status": "completed",
      "totalCents": 5000,
      "currency": "usd",
      "createdAt": "2024-01-15T10:30:00.000Z"
    }
  ],
  "pagination": {
    "total": 8,
    "offset": 0,
    "limit": 20,
    "hasMore": false
  }
}
```