Plan assignments

Plan assignments attach a billing plan to a billing account for an effective time window.

Prereqs

• You can resolve billing_account_id for the target principal: Identity mapping: principal to billing account.
• You have a plan to assign: Plans overview.

Workflow

1. Determine:
   • target billing_account_id
   • target plan
   • source identity (source_kind + source_ref)
   • window start and end (if applicable)
2. Create or upsert the assignment idempotently.
3. Update or cancel it idempotently as customer status changes.

Assignment identity and idempotency

Assignments are idempotent by commercial identity, not by request retries.

Use a stable source tuple:

• billing_account_id
• plan_id
• source_kind
• source_ref

Re-sending the same tuple updates the existing assignment window instead of creating a duplicate assignment row.

Window merge behavior

When the same assignment identity is written again:

• effective start keeps the earlier start
• effective end keeps the farther end
• open-ended windows stay open unless explicitly bounded

This supports repeated sync from provider/sales systems without duplicate plan state.

Status model

Assignment statuses:

• active
• paused
• canceled
• expired

Only active assignments in the effective window participate in runtime bundle selection.

Assignment metadata keys

billing_plan_assignments.metadata can carry behavior inputs. Use only these keys for configuration semantics:

Key path	Purpose
gate_bundle_key	Assignment-level bundle candidate. When present, it is preferred over billing_plans.metadata.gate_bundle_key for that assignment.
billing.period.billing_mode	Assignment-level billing mode override.
billing.period.issue_anchor	Assignment-level issue anchor override.

Use assignment metadata for effective-window-specific overrides. Keep plan metadata for baseline plan semantics.

Verify

• The assignment is visible in management queries for the realm.
• Runtime authorize results match expectations for the account.

Next

• Windows and precedence: Windows and precedence