Changes
Comparing empty → 160dc49.
| @@ -1,0 +1,60 @@ | ||
| 1 | +--- | |
| 2 | +title: Customers | |
| 3 | +sort: 3 | |
| 4 | +--- | |
| 5 | + | |
| 6 | +# Customers | |
| 7 | + | |
| 8 | +A customer is the buyer-side identity. Customers can have many orders, many addresses, and many | |
| 9 | +stored payment methods. | |
| 10 | + | |
| 11 | +## Object | |
| 12 | + | |
| 13 | +| Field | Type | Notes | | |
| 14 | +|-------------------|-----------|---------------------------------------------| | |
| 15 | +| `id` | string | `cust_…` | | |
| 16 | +| `email` | string | Unique within tenant, case-folded | | |
| 17 | +| `name` | string? | Display name | | |
| 18 | +| `phone` | string? | E.164 | | |
| 19 | +| `addresses[]` | array | Default address has `is_default: true` | | |
| 20 | +| `default_currency`| string | ISO 4217 | | |
| 21 | +| `metadata` | object | | | |
| 22 | +| `created_at` | timestamp | | | |
| 23 | + | |
| 24 | +## Endpoints | |
| 25 | + | |
| 26 | +| Method | Path | Purpose | | |
| 27 | +|--------|-------------------------------|--------------------------------------| | |
| 28 | +| `GET` | `/v1/customers` | List | | |
| 29 | +| `POST` | `/v1/customers` | Create | | |
| 30 | +| `GET` | `/v1/customers/{id}` | Retrieve | | |
| 31 | +| `PATCH`| `/v1/customers/{id}` | Update | | |
| 32 | +| `DELETE`| `/v1/customers/{id}` | Anonymise (GDPR-compliant) | | |
| 33 | +| `POST` | `/v1/customers/{id}/merge` | Merge target into source | | |
| 34 | + | |
| 35 | +## Merging customers | |
| 36 | + | |
| 37 | +A common shape: a returning customer signs up with a different email and the storefront creates a | |
| 38 | +new identity. Merge consolidates everything onto the older record. | |
| 39 | + | |
| 40 | +```bash | |
| 41 | +curl -sS https://api.zephyrcart.io/v1/customers/cust_OLDER/merge \ | |
| 42 | + -H "Authorization: Bearer $ZEPHYR_API_KEY" \ | |
| 43 | + -d '{ "target": "cust_NEWER" }' | |
| 44 | +``` | |
| 45 | + | |
| 46 | +What moves: | |
| 47 | + | |
| 48 | +- All carts, orders, and refunds. | |
| 49 | +- All stored payment methods (deduplicated by fingerprint). | |
| 50 | +- All addresses (deduplicated by normalised form). | |
| 51 | +- All metadata (`target` wins on conflict). | |
| 52 | + | |
| 53 | +The `target` customer is then deleted. The operation is not reversible — keep a backup if you | |
| 54 | +need one. | |
| 55 | + | |
| 56 | +## Anonymisation | |
| 57 | + | |
| 58 | +`DELETE /v1/customers/{id}` does not hard-delete. It clears PII (`email`, `name`, `phone`, | |
| 59 | +`addresses`), marks the record `status=anonymised`, and preserves the order history for | |
| 60 | +accounting. Hard deletion requires a separate, audited support ticket. | |