Create a customer unit
Creates a unit for this customer. externalId is your own key for it: required, immutable, and unique within the organization (no other customer’s unit id, external id or alias may be the same, ignoring letter case); every unit route addresses the unit by it, and name defaults to it. Omit parentExternalId to create the customer’s root unit (its first unit; 409 ROOT_EXISTS if it already has one — a customer created with an external id usable as a unit key already has its root, keyed by that external id, so name it as the parent instead); otherwise the parent must exist (409 PARENT_NOT_FOUND) and be ACTIVE. A create whose externalId is one of this customer’s DRAFT units promotes the draft in place: same unit, same id, now ACTIVE with the request’s name, type, metadata and parent (parentExternalId is required; a draft sits under the root). A signal that names a unit before it exists is accepted; with draft units enabled for your organization it creates a DRAFT unit under the customer’s root that holds the key, and creating the unit with that key later promotes the draft; otherwise its spend attaches to the unit once you create it with that key. 409 also when the externalId is taken on this customer (CUSTOMER_UNIT_EXISTS) or by another customer of the organization (EXTERNAL_ID_IN_USE), the tree would get too deep, the customer is on seat-based billing, or a root unit is sent with billable: false (ROOT_UNIT_ALWAYS_BILLABLE). 403 FEATURE_NOT_ENABLED for billable: false when non-billable units are not enabled for your organization. Use the value returned as customer.id, for example cus_abc123; if you have your own customer ID, use the /api/v2/customers/external/{externalId}/… twin.
Authentication
Path parameters
Request
Your own id for the unit: required, immutable, at most 255 characters, and unique within the organization: no other customer's unit id, external id or alias may be the same, ignoring letter case. Every unit route addresses the unit by it (percent-encode it in the path), and so do signals (customerUnit.externalCustomerUnitId). Cannot be . or ...
Display name (defaults to the external ID).
Your structural vocabulary for the unit (department, tenant, team, ...). Free text; filterable; Paid never branches on it.
Your external ID of the parent unit; omit it to create the root unit.
false makes the unit non-billable, together with every unit under it (a dev or QA environment, say). Defaults to true. The root unit is always billable (409 ROOT_UNIT_ALWAYS_BILLABLE): a customer that should never be billed simply has no order. Sending false needs non-billable units enabled for your organization (403 FEATURE_NOT_ENABLED otherwise). 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.
Response
Paid's id for the unit (cu_…), unique within the organization and stable across renames of the customer. For reference only: no unit route accepts it, and routes and signals name a unit by its externalId.
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.