Get a customer unit by its key
Returns a unit by its key without naming its customer. The answer carries the customer’s ids (customerId, customerExternalId) so the customer routes are one hop away, but, like the create on this path, not Paid’s unit id: a caller of these routes names units by key. The key is looked up across the organization ignoring letter case. When more than one unit carries it in another letter case (legacy duplicates across customers, or case variants on one customer), the exact spelling decides; when that does not single one out either, the answer is 409 CUSTOMER_UNIT_AMBIGUOUS: use the customer’s unit routes, where the key is exact.
Authentication
Path parameters
Your id of the unit (its externalId), unique within the organization ignoring letter case.
Response
Your own id for the unit, unique within the customer; the identifier every unit route takes.
Paid's id of the customer the unit belongs to (cus_…). null only for a legacy customer that has no Paid id; customerExternalId still names it.
ACTIVE; DELETED after a soft delete (one-way); or DRAFT, a placeholder that holds the key for this customer until you create the unit with that key (which promotes it) or delete it (soft, the key stays reserved, as for any unit). A draft is never a parent and never carries a cap.
externalId of the parent unit; null only on the customer's root unit.
Whether this unit is the customer's root: the one unit without a parent. Derived from the missing parent, not stored. At most one active root per customer; the root cannot be moved, and once deleted a new root can be created.
The unit's own setting, as last created or updated: false marks it, and every unit under it, non-billable. Always true on the root. effectiveBillable says whether the unit is billable once its ancestors are counted. Usage on a non-billable unit is still recorded but not billed: it burns no credits, adds nothing to invoices or overage, and counts toward no cap, on a price whose usage comes from a meter (read from your events when the invoice closes) too. A meter's derived signal, and a correlation-window meter's window, follow the source event they take their unit from (the window's closing event, else its opening event): they are not billed when that event was not. Usage is still billed when it is sent with a customer API key, and on cost-plus pricing, which bills from costs that carry no unit. Only signals sent to /api/v2/signals that resolve to an active unit, by its key or through an alias on it, can be non-billable, and a change applies to signals received afterwards.
Read-only. Whether the unit is billable in effect: false when the unit or any unit above it has billable: false. A unit cannot make itself billable under a non-billable ancestor, and moving a unit under one makes it non-billable.