FAQ

Should principal_id be a user id?

Usually no. Use the most stable billing-owner identifier you already have as principal_id, and send the runtime end user separately as user_id.

• If billing is truly per-user, the same stable application identifier may be used for both principal_id and user_id.
• If billing is shared by an org, team, or workspace, use that stable org/team/workspace id.
• If ownership can change later, avoid using a transient login or context id directly. Choose a stable internal billing-owner id instead.

Can I retry a timed out write?

Yes. Retry with the same Idempotency-Key and the same body.

How do I obtain billing_account_id?

Use POST /mgt/v1/token/issue from your backend with principal_id and user_id. The response includes billing_account_id and billing_user_id.