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 payload​

grant_programs.eligibility_payload is consumed with eligibility_kind.

  • For eligibility_kind=subscription_group, supported targeting keys are:
    • subscription_group_id
    • group_key

Assignment override payload​

grant_assignments.metadata.grant_override is the assignment-level override carrier.

Typical keys include:

  • grant_program_code
  • amount_xusd
  • priority_override
  • kind_override
  • on_ledger_override
  • issue_anchor_override
  • window_kind_override
  • window_relative_seconds_override
  • alloc_seq_override
  • scale_by_invoice_quantity
  • nested metadata

Use this for controlled, explicit exceptions. Keep baseline commercial policy in grant programs.

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​

  • Using program mode with non-one-time manual-eligibility programs.
  • Treating consumption entries as mutable ledger.
  • Deleting active campaigns without checking assignment linkage.

Next​