# Grant blocks

> For the complete machine-readable documentation index, see [llms.txt](https://apidocs.chargebee.com/llms.txt).


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](/docs/api/item_prices) or via the [allocate](/docs/api/ledger_operations/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**](#provisioned_block_balance) and [**overdraft\_block\_balance**](#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**](#effective_from) time, after which it expires. If a rollover policy is configured, any unused credit grants at [**expires\_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[](#grant-blocks-lifecycle)

![Grant Blocks LifeCycle](/images/grant_blocks_lifecycle.png)

## Lifecycle Of Credit Grants In A Block[](#lifecycle-of-credit-grants-in-a-block)

![LifeCycle Of Credit Grants In A Block](/images/life_cycle_of_credits.png)

## Sample Grant block

```json
{
  "grant_block": {
    "id": "gb_ai_credits_001",
    "subscription_id": "1mGETgZVF2umUZq",
    "unit_id": "ai_credits",
    "unit_type": "credit_unit",
    "account_type": "provisioned",
    "effective_from": 1746723600,
    "expires_at": 1775402925,
    "status": "available",
    "grant_source": "subscription_created",
    "created_at": 1746723600,
    "modified_at": 1774978599,
    "resource_version": 1774978599000,
    "object": "grant_block",
    "provisioned_block_balance": {
      "granted_amount": "100.25",
      "total_balance": "100.25",
      "usable_balance": "49.7975",
      "hold_amount": "50.4525",
      "used_amount": "0",
      "expired_amount": "0",
      "rolled_over_amount": "0",
      "voided_amount": "0"
    },
    "overdraft_block_balance": null
  }
}
```

## Grant blocks attributes

## Input Parameters

- `id` (required, string, max chars=50)
  A unique identifier for this grant block.
  
  **Behavior**
  
  -   Automatically assigned by the ledger at creation time.
  -   Immutable and cannot be modified once written.

- `subscription_id` (required, string, max chars=50)
  Identifier of the subscription this grant block belongs to.

- `unit_id` (required, string, max chars=50)
  Identifier of the credit unit this block belongs to. For example, a credit unit id such as `ai_credits`.

- `unit_type` (required, enumerated string)
  Type of unit used for this balance. For example, `credit_unit` for credit grants.
  Possible enum values:
    - `credit_unit`
      The unit represents a credit unit, the type used by credit grants.

- `account_type` (required, enumerated string)
  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).
  Possible enum values:
    - `provisioned`
      Stores the credit grants given as per the plan configuration. Consumption of credit grants is first done through this account.
    - `overdraft`
      Allows consumption beyond the configured credit grants. Used once the credit grants in the provisioned account are exhausted.

- `effective_from` (required, timestamp(UTC) in seconds)
  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.

- `expires_at` (required, timestamp(UTC) in seconds)
  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.

- `origin_grant_block_id` (optional, string, max chars=50)
  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.

- `status` (required, enumerated string, default=available)
  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.
  Possible enum values:
    - `available`
      The block is effective and credit grants are consumable subject to remaining balance and holds.
    - `exhausted`
      No usable credit grants remain; the block was fully consumed, expired, voided, or rolled over.
    - `scheduled`
      The block exists but `effective_from` is still in the future, so credit grants are not yet spendable.
    - `in_grace_period`
      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).

- `grant_source` (required, enumerated string)
  Enumerated string indicating the event or action that resulted in these credit grants being issued.
  Possible enum values:
    - `subscription_created`
      Issued when the subscription was created (initial allocation as per the plan configuration).
    - `subscription_changed`
      Issued in response to a subscription change that triggers a new allocation (for example, a plan or addon update that adjusts the credit grants).
    - `top_up`
      Issued from a top-up purchase or similar add-on credit-grant purchase made on top of the configured plan.
    - `promotional_grants`
      Issued from the [allocate](/docs/api/ledger_operations/allocate) operation (for example, marketing offers or goodwill credits).
    - `rollover`
      Issued by carrying forward unused credit grants from another block at end-of-period processing.
    - `grant_renewal`
      Issued when a grant is renewed for the next cycle by the grant renewal process (recurring re-grant of the configured credits).
    - `subscription_renewed`
      Issued when the subscription renews for a new term, triggering a fresh allocation of the configured credit grants.

- `created_at` (required, timestamp(UTC) in seconds)
  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.

- `modified_at` (required, timestamp(UTC) in seconds)
  Unix timestamp (seconds) when the grant block was last updated.

- `resource_version` (optional, long)
  Version number of this resource. The `resource_version` is updated with a new timestamp for every change made to the resource.

- `metadata` (optional, jsonobject)
  Optional opaque JSON object carrying additional business context
  
  **Behavior**
  
  -   Stored as-is and returned verbatim by the ledger.
  -   Not interpreted, validated, or indexed by the ledger.

- `provisioned_block_balance` (optional, provisioned_block_balance)
  Balance details for a grant block with provisioned [`account_type`](#account_type).
  
  **Note**
  
  Populated only for blocks with provisioned `account_type`; `null` for overdraft blocks.
  - `granted_amount` (optional, string, max chars=36)
    The total number of credit grants issued to this grant block when it was created. This value represents the maximum credits the block can provide over its lifetime. Returned as a decimal string.
    
    **Constraints**
    
    Maximum supported value: `9999999999999999999999999.9999999999` (up to 25 digits before the decimal and up to 10 digits after).
  - `total_balance` (optional, string, max chars=36)
    Total credits remaining in this grant block, including held amounts (`usable_balance` + `hold_amount`). Returned as a decimal string.
    
    **Constraints**
    
    Maximum supported value: `9999999999999999999999999.9999999999` (up to 25 digits before the decimal and up to 10 digits after).
  - `usable_balance` (optional, string, max chars=36)
    Remaining usable credits in this grant block available for consumption (excludes held amount). Returned as a decimal string.
    
    **Constraints**
    
    Maximum supported value: `9999999999999999999999999.9999999999` (up to 25 digits before the decimal and up to 10 digits after).
  - `hold_amount` (optional, string, max chars=36)
    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.
    
    **Constraints**
    
    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 `usable_balance` is 75 and `hold_amount` is 5.
  - `used_amount` (optional, string, max chars=36)
    Total credits consumed from this block through consumption operations (captures and capture authorizations). Returned as a decimal string.
    
    **Constraints**
    
    Maximum supported value: `9999999999999999999999999.9999999999` (up to 25 digits before the decimal and up to 10 digits after).
  - `expired_amount` (optional, string, max chars=36)
    The portion of credit grants in this block that expired without being consumed, rolled over, or voided. Returned as a decimal string.
    
    **Constraints**
    
    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.
  - `rolled_over_amount` (optional, string, max chars=36)
    The portion of credits carried forward from this block into a new rollover block during end-of-period processing. Returned as a decimal string.
    
    **Constraints**
    
    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 `provisioned_block_balance.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.
  - `voided_amount` (optional, string, max chars=36)
    The portion of credits removed from this block through administrative void operations. Returned as a decimal string.
    
    **Constraints**
    
    Maximum supported value: `9999999999999999999999999.9999999999` (up to 25 digits before the decimal and up to 10 digits after).
    
    **Behavior**
    
    -   Voided credits reduce the remaining usable 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.

- `overdraft_block_balance` (optional, overdraft_block_balance)
  Balance details for a grant block with overdraft [`account_type`](#account_type).
  
  **Note**
  
  Populated only for blocks with overdraft `account_type`; `null` for provisioned blocks.
  - `is_unlimited` (required, boolean, default=false)
    Whether the overdraft block has no limit (`true`) or is capped (`false`). When `true`, `limit`, `total_balance`, and `usable_balance` are `null`.
  - `limit` (optional, string, max chars=36)
    The maximum overdraft credits allowed for this block. Returned as a decimal string; `null` when [`is_unlimited`](#overdraft_block_balance.is_unlimited) is `true`.
    
    **Constraints**
    
    Maximum supported value: `9999999999999999999999999.9999999999` (up to 25 digits before the decimal and up to 10 digits after).
  - `total_balance` (optional, string, max chars=36)
    Total overdraft credits remaining in this block, including held amounts. Returned as a decimal string; `null` when [`is_unlimited`](#overdraft_block_balance.is_unlimited) is `true`.
    
    **Constraints**
    
    Maximum supported value: `9999999999999999999999999.9999999999` (up to 25 digits before the decimal and up to 10 digits after).
  - `usable_balance` (optional, string, max chars=36)
    Remaining usable overdraft credits in this block available for consumption. Returned as a decimal string; `null` when [`is_unlimited`](#overdraft_block_balance.is_unlimited) is `true`.
    
    **Constraints**
    
    Maximum supported value: `9999999999999999999999999.9999999999` (up to 25 digits before the decimal and up to 10 digits after).
  - `used_amount` (optional, string, max chars=36)
    Total overdraft credits consumed from this block. Returned as a decimal string.
    
    **Constraints**
    
    Maximum supported value: `9999999999999999999999999.9999999999` (up to 25 digits before the decimal and up to 10 digits after).