A grant block represents a bucket of issued credit grants associated with a given subscription, unit_id, and unit_type, allocated either through an item price or via the allocate operation.
Each grant block follows its own lifecycle, governed by a defined policy that manages how the credit grants within the block are consumed, held, expired or rolled over.
Example
An annual subscription plan grants 100 AI credits every month, resulting in a new grant block of 100 credit grants being allocated to the subscription at the start of each grant cycle.
During its lifecycle, the block tracks usage through the balance fields grouped under provisioned_block_balance and overdraft_block_balance (for example, used_amount, hold_amount, and usable_balance).
Since the grant frequency is monthly, each block has a validity of one month from its effective_from time, after which it expires. If a rollover policy is configured, any unused credit grants at expires_at may be carried forward into a new grant block; otherwise, they expire.
This process repeats each month as long as the subscription remains active, creating a sequence of time-bound grant blocks that independently track and manage their respective credit grants.
Grant Blocks Lifecycle
Lifecycle Of Credit Grants In A Block
Sample Grant blockJSON
Grant blocks attributes
The account this block belongs to: provisioned (credit grants issued per the plan, consumed first) or overdraft (consumption beyond the configured credit grants, after the provisioned account is exhausted).
Stores the credit grants given as per the plan configuration. Consumption of credit grants is first done through this account.
Allows consumption beyond the configured credit grants. Used once the credit grants in the provisioned account are exhausted.
Unix timestamp (in seconds) indicating when this grant block becomes active and its credits become available for use.
Behavior
- Allocations scheduled for the future are valid but remain non-spendable until this time.
- Prior to this timestamp, the block is in a scheduled state.
Activation
At effective_from, the block becomes active and its credits are included in the usable balance of the account.
Note
effective_from is inclusive (bounded). Any capture operation with a timestamp exactly equal to effective_from is eligible to consume credits from this block.
Unix timestamp (in seconds) indicating when this grant block stops being directly consumable.
Behavior
- At expires_at, the block transitions from available to in_grace_period.
- During the grace period, eligible late-arriving operations may still consume credits based on their operation_timestamp.
Finalization After the grace period ends, any remaining balance is finalized as expired or rolled over, depending on the configured rollover policy.
Note
expires_at is exclusive (unbounded). Any capture operation with a timestamp exactly equal to expires_at is not eligible to consume credits from this block.
Identifier of the source (originating) grant block from which this block was derived.
Behavior
- Populated only when this block is created through a rollover.
- References the block whose remaining balance was carried forward into this block.
Usage
Enables traceability between original and rollover blocks for audit and reporting purposes.
Enumerated string representing the current lifecycle state of the grant block.
Example
A block moves from scheduled → available → in_grace_period → exhausted over its lifecycle.
The block is effective and credit grants are consumable subject to remaining balance and holds.
No usable credit grants remain; the block was fully consumed, expired, voided, or rolled over.
The block exists but effective_from is still in the future, so credit grants are not yet spendable.
Past expires_at but within the configured grace period; limited consumption is still allowed for eligible
operations (those whose operation_timestamp falls within the original validity window).
Enumerated string indicating the event or action that resulted in these credit grants being issued.
Issued when the subscription was created (initial allocation as per the plan configuration).
Issued in response to a subscription change that triggers a new allocation (for example, a plan or addon update that adjusts the credit grants).
Issued from a top-up purchase or similar add-on credit-grant purchase made on top of the configured plan.
Issued from the allocate operation (for example, marketing offers or goodwill credits).
Issued by carrying forward unused credit grants from another block at end-of-period processing.
Issued when a grant is renewed for the next cycle by the grant renewal process (recurring re-grant of the configured credits).
Issued when the subscription renews for a new term, triggering a fresh allocation of the configured credit grants.
Unix timestamp (in seconds) indicating when this grant block was recorded in the ledger.
Behavior
- Automatically set by the ledger at creation time.
- Immutable and cannot be modified after being written.
Usage
Provides a reliable reference for auditability and chronological ordering of grant blocks.
Balance details for a grant block with provisioned account_type.
Note
Populated only for blocks with provisioned account_type; null for overdraft blocks.
Balance details for a grant block with overdraft account_type.
Note
Populated only for blocks with overdraft account_type; null for provisioned blocks.