A grant block represents a bucket of issued credits associated with a specific subscription, unit_id, and unit_type, allocated either through an item price or as a promotional grant.
Each grant block follows its own lifecycle, governed by a defined policy that manages how the credits 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 credits being allocated to the subscription at the start of each grant cycle.
During its lifecycle, the block tracks usage through fields such as used_amount, hold_amount, and the 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 credits 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 credits.
Grant Blocks Lifecycle
Lifecycle Of Credits In A Block
Sample Grant blockJSON
API Index URL
Grant blocks attributes
The total number of credit grants issued to the grant block when it is created. This value represents the maximum credits the block can provide over its lifetime.
Returned as a decimal string. Maximum supported value: 9999999999999999999999999.9999999999 (up to 25 digits before the decimal and up to 10 digits after).
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.
Represents the remaining usable credits within this grant block, i.e., the portion of this specific block that is still available for consumption.
Returned as a decimal string. Maximum supported value: 9999999999999999999999999.9999999999 (up to 25 digits before the decimal and up to 10 digits after).
Represents the portion of credit grants temporarily reserved by active authorization operations on this block, which are not yet captured or released.
Returned as a decimal string. Maximum supported value: 9999999999999999999999999.9999999999 (up to 25 digits before the decimal and up to 10 digits after).
Behavior These reserved credits are not considered consumed. However, they are excluded from the remaining usable balance until the authorization is either completed (captured) or canceled (released).
Example
If a block has 100 credits, with 20 used and 5 on hold, the balance is 75 and hold_amount is 5.
Represents the total credits consumed from this block through consumption operations, specifically debits resulting from capture and capture_authorization.
Returned as a decimal string. Maximum supported value: 9999999999999999999999999.9999999999 (up to 25 digits before the decimal and up to 10 digits after).
Represents the portion of credit grants in this block that expired without being consumed, rolled over, or voided.
Returned as a decimal string. Maximum supported value: 9999999999999999999999999.9999999999 (up to 25 digits before the decimal and up to 10 digits after).
Lifecycle Behavior
- The block becomes consumable at effective_from and remains directly usable until expires_at.
- After expires_at, the block enters the configured grace period.
- During this grace period, late-arriving operations with an operation_timestamp within the original validity window may still consume credits from this block.
Finalization
Once the grace period ends, any remaining unconsumed credits are finalized and recorded as expired_amount.
Example
If a block expires at 10:00 and has a 6-hour grace period, a usage event with an operation_timestamp of 9:55 can still consume credits during the grace window.
Represents the portion of credits carried forward from this block into a new rollover block during end-of-period processing.
Returned as a decimal string. Maximum supported value: 9999999999999999999999999.9999999999 (up to 25 digits before the decimal and up to 10 digits after).
Source vs Destination Behavior
- On the source block, this amount reflects the remaining balance that has been moved out and is no longer spendable.
- On the destination (rollover) block, the same amount is recorded under granted_amount as the value of the new block.
Reporting Semantics
Tracked separately from expired_amount to clearly distinguish credits that were preserved via rollover from those that expired.
Represents the portion of credits removed from this block through administrative void operations.
Returned as a decimal string. Maximum supported value: 9999999999999999999999999.9999999999 (up to 25 digits before the decimal and up to 10 digits after).
Behavior
- Voided credits reduce the remaining balance of the block.
- They are not included in used_amount.
Reporting Semantics
Tracked separately to ensure usage reports and revenue reconciliation exclude voided credits while maintaining a complete audit trail.
Example
If 10 credits are revoked due to a cancellation, they are added to voided_amount and not counted as usage.
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 a promotional or courtesy credit-grants program (for example, marketing offers or goodwill credits).
Issued by carrying forward unused credit grants from another block at end-of-period processing.
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.
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.