# Customers

> Customers, ingest aliases and how lookups work.

Source: https://metrocli.com/docs/concepts/customers/ · Docs index: https://metrocli.com/llms.txt

A customer is the Metronome record for the account you bill. It has a stable Metronome UUID, a name, ingest aliases, custom fields, and billing provider configurations.

> **Metronome's reference:** [Create a customer](https://docs.metronome.com/api-reference/customers/create-a-customer) · [List customers](https://docs.metronome.com/api-reference/customers/list-customers) · [Create or update customer ingest aliases](https://docs.metronome.com/api-reference/customers/create-or-update-customer-ingest-aliases) · [Archive a customer](https://docs.metronome.com/api-reference/customers/archive-a-customer) · [Set custom field values](https://docs.metronome.com/api-reference/custom-fields/set-custom-field-values). These pages are the source of truth for every field; metro's page covers how metro handles it. What metro wraps, endpoint by endpoint: [Metronome API coverage](/docs/reference/api-coverage).

## How it connects

- **Usage events** reach a customer through `customer_id`, which can be the Metronome ID or any of its **ingest aliases**, for example `acme-corp`.
- **Contracts** reference `customer_id`.
- **Billing provider configs** (for example Stripe) attach to the customer. Contracts inherit them unless a contract sets its own.
- **Hierarchies** are declared on the child's contract, not on the customer: the child contract points at the parent's `customer_id` and `contract_id`.

## Gotchas

- Ingest aliases must be unique across the tenant. A collision returns `409` with `conflicting_id`.
- Setting ingest aliases replaces the whole list. An alias you leave out is removed.
- Archiving a customer archives all of its contracts and voids its finalized invoices. It does not refund Stripe.
- Archived customers keep their ingest aliases until you set an empty list on them.
- Custom field keys must be allowlisted per entity before use. One unknown key fails the whole write, and each value is limited to 200 characters.
- A hierarchy holds at most 10 nodes: one parent and nine children.
- `POST /v1/customers` takes no `uniqueness_key`.

## How metro handles it

- **Lookups.** `metro ops who`, `metro customer resolve` and every op take one of `--customer-id=`, `--external-id=`, `--ingest-alias=` or `--name=`. Metronome has no server-side name filter, so a name lookup stops at the first exact match; an email-shaped name routes through the ingest alias in one call. Pass an ID when uniqueness matters.
- **Create.** `metro customer create preflight --name=... --ingest-alias=...` makes the aliases the idempotency anchor. It needs at least one, refuses any alias that belongs to an active or archived customer, and checks again just before writing, so the same plan can't create two customers. See [Provision a package](/docs/guides/provision-a-package).
- **External IDs.** `--external-id=` writes into the custom field named by `--external-id-field`, which defaults to the first key in `METRO_EXTERNAL_ID_FIELDS`, or `external_id`.

| Command | Does |
|---|---|
| `metro ops who "Acme Corp" --sandbox` | Customer, active contracts and nonzero balances |
| `metro customer resolve --ingest-alias=acme-corp --sandbox --json` | Resolve one customer |
| `metro customer create preflight` / `apply` | Create a customer with aliases, custom fields and optional Stripe config |
| `metro customer setup preview --file customer.json --sandbox` | Offline preview of the `customer-setup` shape |

Metronome docs: [Create a customer](https://docs.metronome.com/api-reference/customers/create-a-customer).