Skip to main content

Direct plan assignment

Direct plan assignment is the recommended path for sales-led and enterprise workflows where your system already owns commercial decisions.

Instead of relying on provider checkout as source of truth, your backend assigns the effective plan to a billing account with explicit effective windows.

Prereqs​

Ownership boundaries​

  • CPQ/CRM/subscription system owns contract intent.
  • Vluna owns runtime enforcement and billing behavior for effective assignment state.
  • Support tooling must be able to answer "which plan was effective at timestamp T".

Assignment workflow​

  1. Commercial system determines target plan and effective window.
  2. Backend writes assignment idempotently with stable source identity.
  3. Backend verifies effective assignment readback.
  4. Runtime gate loop reflects assignment state through authorize and commit.

Reliability requirements​

  • Use idempotency keys for all assignment writes.
  • Keep source_kind + source_ref stable across retries and sync jobs.
  • Never trust client-provided billing_account_id without server-side mapping validation.
  • Keep assignment changes auditable (operator, reason, ticket_id, effective_at).

Metadata guidelines for direct assignment​

When you need per-assignment overrides, use:

  • metadata.gate_bundle_key
  • metadata.billing.period.billing_mode
  • metadata.billing.period.issue_anchor

Keep long-lived defaults in plan metadata, and use assignment metadata only for window-scoped exceptions.

Source-kind guidance​

Choose source kinds by ownership:

  • ops.manual for support/ops decisions
  • ops.campaign for managed rollout campaigns
  • provider source kinds for provider-derived subscription state

Do not mix multiple source identities for the same commercial event.

Verify​

  • The expected assignment is active for the expected window.
  • Upgrade and downgrade transitions are explainable for any timestamp.
  • Runtime decisions and pricing outputs match assigned plan semantics.

Next​