Entities

An entity is something your customer has many of. Creating one can use up a unit of a feature (a seat), and each entity can have its own plan and balances, such as 50 credits per user per month.

entities.createCopy Anchor Link

{ "customer_id": "org_42", "entity_id": "user_7", "feature_id": "seats", "name": "Abena Mensah" }

With feature_id, creating the entity tracks one unit of that feature on the customer. If no seat is left the call fails with 402 and nothing is created. On a pay as you go seat item, extra seats are charged for the days left in the period, or at renewal, depending on the item's proration. Creating an entity that already exists answers it with created: false.

{
  "id": "user_7",
  "customer_id": "org_42",
  "feature_id": "seats",
  "name": "Abena Mensah",
  "created": true,
  "subscriptions": [],
  "balances": {},
  "flags": {},
  "billing_controls": { "overage_allowed": [], "spend_limits": [], "usage_limits": [], "usage_alerts": [], "auto_topups": [] }
}

Plans and balances per entityCopy Anchor Link

Pass entity_id to billing.attach, balances.check, balances.track, balances.create and plans.list. A check with an entity_id uses the entity's own balance first and falls back to the customer's, so shared credit pools and per seat allowances can live side by side.

entities.updateCopy Anchor Link

{ "customer_id", "entity_id", "name"?, "metadata"?, "billing_controls"? }. Entity limits replace the customer's for the same feature; a usage limit set on an entity counts that entity's usage only. Auto top ups belong to the customer and cannot be set here.

entities.deleteCopy Anchor Link

{ "customer_id", "entity_id" } ends the entity's plans and gives its seat back.

entities.get and entities.listCopy Anchor Link

entities.get takes { "customer_id", "entity_id" }. entities.list takes { "customer_id"?, "feature_id"?, "limit"?, "start_cursor"? }.