---
title: Customers
sort: 3
---

# Customers

A customer is the buyer-side identity. Customers can have many orders, many addresses, and many
stored payment methods.

## Object

| Field             | Type      | Notes                                       |
|-------------------|-----------|---------------------------------------------|
| `id`              | string    | `cust_…`                                    |
| `email`           | string    | Unique within tenant, case-folded           |
| `name`            | string?   | Display name                                |
| `phone`           | string?   | E.164                                       |
| `addresses[]`     | array     | Default address has `is_default: true`      |
| `default_currency`| string    | ISO 4217                                    |
| `metadata`        | object    |                                             |
| `created_at`      | timestamp |                                             |

## Endpoints

| Method | Path                          | Purpose                              |
|--------|-------------------------------|--------------------------------------|
| `GET`  | `/v1/customers`               | List                                 |
| `POST` | `/v1/customers`               | Create                               |
| `GET`  | `/v1/customers/{id}`          | Retrieve                             |
| `PATCH`| `/v1/customers/{id}`          | Update                               |
| `DELETE`| `/v1/customers/{id}`         | Anonymise (GDPR-compliant)           |
| `POST` | `/v1/customers/{id}/merge`    | Merge target into source             |

## Merging customers

A common shape: a returning customer signs up with a different email and the storefront creates a
new identity. Merge consolidates everything onto the older record.

```bash
curl -sS https://api.zephyrcart.io/v1/customers/cust_OLDER/merge \
  -H "Authorization: Bearer $ZEPHYR_API_KEY" \
  -d '{ "target": "cust_NEWER" }'
```

What moves:

- All carts, orders, and refunds.
- All stored payment methods (deduplicated by fingerprint).
- All addresses (deduplicated by normalised form).
- All metadata (`target` wins on conflict).

The `target` customer is then deleted. The operation is not reversible — keep a backup if you
need one.

## Anonymisation

`DELETE /v1/customers/{id}` does not hard-delete. It clears PII (`email`, `name`, `phone`,
`addresses`), marks the record `status=anonymised`, and preserves the order history for
accounting. Hard deletion requires a separate, audited support ticket.