Skip to main content

Grants operations

This guide documents business semantics across programs, assignments, grants, and campaigns.

Object responsibilities​

  • Program defines issuance policy template.
  • Assignment binds template to account/source context.
  • Grant is the consumable lot with lifecycle and balances.
  • Campaign orchestrates bulk issuance windows and targeting.

JSON contracts you should standardize​

Program eligibility​

eligibility_kind supports manual and all_accounts. Neither mode currently consumes targeting keys from eligibility_payload. Subscription targeting is expressed by Catalog Price to Billing Plan mapping, not by Grant Program eligibility.

Public grant bindings​

Plan, catalog, and campaign bindings all use exact {grant_program_code, amount_xusd} objects. Both fields are required, a program may appear only once in one source, and no structural override or binding metadata is accepted. Catalog bindings may reference only cadence=once programs and only for one-time Prices. Recurring Prices must map to a Billing Plan; Plan bindings own all recurring Subscription grants.

Keep cadence, anchor, window, kind, priority, ledger, and outstanding-balance behavior in the grant program. Create another program when a flow needs different mechanics.

Manual assignment creation likewise accepts a required top-level amount_xusd; public metadata is annotations only. Vluna may carry the validated amount through private assignment metadata internally, but grant_override and grants are reserved implementation keys and are not public configuration surfaces.

Critical invariants​

  • Cross-account operations are scope-gated; account mismatch is blocked unless elevated access allows it.
  • Manual grant and program grant are distinct issuance modes with different validation rules.
  • Grant consumption entries are derived from allocation facts, not independent write streams.
  • Campaign deletion is conditional (hard delete vs soft-close) based on assignment references.
  • Compensation use-case: manual issuance with strict idempotency discipline.
  • Productized credit use-case: program mode with explicit program governance.
  • Large rollout use-case: campaign orchestration + assignment linkage + post-run closeout.

Audit and control guidance​

  • Always capture operator intent (reason, ticket, source reference).
  • Prefer compensating grants/closures over destructive mutation.
  • Keep grant state transitions explicit (issuance_status, closure_kind) and reviewable.

High-risk mistakes​

  • Treating a Subscription group as Grant Program eligibility instead of mapping its recurring Price to a Billing Plan.
  • Binding recurring grants directly to Catalog Products or Prices.
  • Treating consumption entries as mutable ledger.
  • Deleting active campaigns without checking assignment linkage.

Next​