> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orquestr.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Customers

> Create and manage customers.

# Customers

Base: `/v1/customers`. Authenticate with an **API key**:

```http theme={"system"}
Authorization: Bearer sk_live_…
```

| Method   | Path   | Body / params                                          |
| -------- | ------ | ------------------------------------------------------ |
| `POST`   | `/`    | `{ name, external_customer_id? }`                      |
| `GET`    | `/`    | `?external_customer_id=`, optional `page` / `per_page` |
| `GET`    | `/:id` | path `id`                                              |
| `PATCH`  | `/:id` | `{ name?, external_customer_id? \| null }`             |
| `DELETE` | `/:id` | —                                                      |

Responses use the standard [envelope](/api/introduction#response-shape): `{ data }` for single resources, `{ data, meta }` for lists.

## External id

Optional `external_customer_id` (string, max 200). Trimmed; empty → `null`. Unique per account owner when set (`409` on conflict). Returned on all customer payloads. Filter list with `?external_customer_id=`.

## Create customer

```bash theme={"system"}
curl --request POST \
  --url https://api.orquestr.dev/cloud/v1/customers \
  --header 'Authorization: Bearer sk_live_…' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "Mi tienda",
  "external_customer_id": "acme-store-01"
}'
```

| Field                  | Type           | Required | Notes                              |
| ---------------------- | -------------- | -------- | ---------------------------------- |
| `name`                 | string         | Yes      | 1–200 chars                        |
| `external_customer_id` | string \| null | No       | Integration id; unique per account |

Example response:

```json theme={"system"}
{
  "data": {
    "id": "o2222222-2222-2222-2222-222222222222",
    "name": "Mi tienda",
    "owner_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "external_customer_id": "acme-store-01",
    "created_at": "2026-09-01T15:05:00.000Z",
    "updated_at": "2026-09-10T09:00:00.000Z"
  }
}
```

## List / filter

```bash theme={"system"}
curl -s "$API/v1/customers?external_customer_id=acme-store-01" \
  -H "Authorization: Bearer $ORQUESTR_API_KEY"
```

Example response:

```json theme={"system"}
{
  "data": [
    {
      "id": "o2222222-2222-2222-2222-222222222222",
      "name": "Mi tienda",
      "owner_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "external_customer_id": "acme-store-01",
      "created_at": "2026-09-01T15:05:00.000Z",
      "updated_at": "2026-09-10T09:00:00.000Z"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 1,
    "total_pages": 1,
    "total_count": 1
  }
}
```

Optional `page` / `per_page` (max 100). If both omitted, returns the full set with `meta` reflecting the full count.

## Delete customer

```bash theme={"system"}
curl -s -X DELETE "$API/v1/customers/$CUSTOMER_ID" \
  -H "Authorization: Bearer $ORQUESTR_API_KEY"
```

Returns `{ "data": { "ok": true } }` on success.

Deletion is **blocked** (`409 conflict`) while the customer still has:

* **Active licenses** — `status = active` (revoke first)
* **Active devices** — `status = pending` or `enrolled` (revoke first)
* Unrevoked API keys