Skip to main content

Billing accounts and billing details

This guide focuses on semantics and operator rules that API Reference cannot express.

What this object means​

  • billing_accounts is the tenancy anchor for all account-scoped billing data.
  • billing_account_billing_details is mutable business profile data attached to that anchor.
  • Account identity (billing_account_id) and business profile (billing details) have different lifecycle and should not be coupled in product logic.

Invariants​

  • Realm boundary is hard: updates only succeed when account belongs to current realm.
  • Billing details update is patch/upsert, not replace.
  • Empty patch is rejected.
  • last_updated_by is normalized to ops on this management path.
  • Returned tax IDs are masked views, not raw source values.

Design implications​

  • Treat billing details as profile state, not authorization state.
  • Do not infer entitlement, risk, or account ownership from billing details fields.
  • Do not build workflows that require destructive reset; update is intentionally additive/patch-like.

Operational guidance​

  • Always keep an external audit trail (ticket_id, operator, reason) in your own system and/or metadata.
  • For sensitive fields, prefer explicit change ticketing and dual control, since management writes are realm-admin scoped.
  • When debugging mismatches, first validate realm/account mapping, then profile content.

Failure patterns worth documenting​

  • Account exists globally but not in current realm context.
  • Client sends syntactically valid request but no actual field change.
  • Consumer expects full tax payload but receives masked representation by design.

Next​