customers

Delete a customer unit

Soft-deletes a unit: it stays readable with status: DELETED and cannot be reactivated. Spend history that references it is kept, and signals that keep naming it are still attributed to it. A DRAFT unit is deleted the same way: it stays readable as DELETED, its key stays reserved, and spend already keyed to it stays its own. 409 while the unit has ACTIVE or DRAFT children or a cap in force or scheduled; the root follows the same rules, and once it is deleted a new root can be created. 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.

delete/customers/{id}/customer-units/{externalCustomerUnitId}

Request

  • Base URL: https://api.agentpaid.io/api/v2
  • URL: https://api.agentpaid.io/api/v2/customers/{id}/customer-units/{externalCustomerUnitId}
  • Auth: HTTP bearer

Path parameters

idstring required

Paid customer display id

externalCustomerUnitIdstring required

Your own id for the unit (its externalId), unique within this customer.

Response

200

idstring required

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.

externalIdstring required

Your own id for the unit, unique within the customer; the identifier every unit route takes.

customerIdstring nullable required

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.

customerExternalIdstring nullable required

Your external id of that customer, when it has one.

namestring required

Display name. Never used to address the unit.

externalTypestring nullable required

Your structural vocabulary for the unit.

status'ACTIVE' | 'DELETED' | 'DRAFT' required

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.

parentExternalIdstring nullable required

externalId of the parent unit; null only on the customer's root unit.

isRootboolean required

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.

billableboolean required

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.

effectiveBillableboolean required

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.

metadataobject nullable required
createdAtstring date-time required
updatedAtstring date-time required

Changes

No recorded changes to this operation across all 1 revision of this API.