Reserves credit grants at the time of request for later finalization via capture_authorization or release_authorization.
Use this operation when the upstream system requires a strict balance check before finalizing consumption. Credits are moved to a held state immediately, preventing concurrent operations from spending the same credits.
API Behavior
- Moves credits from usable balance → held (reserved) state.
- No consumption occurs at this stage; only reservation.
- Final state is determined later:
capture_authorization: converts held credits into consumed.release_authorization: returns held credits to usable balance.
Reserved Credits Behavior
- Held credits are not consumable by other operations.
- Held credits are not counted as used until captured.
- Unreleased holds are automatically returned to usable balance upon expiry.
Use Cases
- Concurrency control
- Prevents multiple simultaneous operations from overspending the same credits.
- Ensures credits are reserved for a specific flow while other requests see reduced availability.
Two-step workflows Supports "check now, finalize later" flows.
The response returns both the created ledger_operation object and the updated ledger_account_balance.
Sample Request
Sample Result[JSON]
URL Format
Input Parameters
Optional client-supplied identifier for this authorize operation.
Behavior
- When provided, must uniquely identify this operation across the entire ledger.
- Should not conflict with any other operation, regardless of type.
Usage
- Identifies the specific reservation of credits created by this request.
- Used as the reference for subsequent operations:
capture_authorization: to finalize (consume) the held credits.release_authorization: to release the held credits back to usable balance.
A unique, immutable identifier for the subscription against which credit grants are tracked.
The number of credit grants to reserve from the usable balance. While held, this amount is unavailable for other operations, helping prevent concurrent requests from spending the same credits.
Pass this value as a decimal string. Maximum supported value: 9999999999999999999999999.9999999999 (up to 25 digits before the decimal and up to 10 digits after).
Behavior
- On
authorize, this amount is moved fromusable_balancetohold_amount. It is not consumed yet. - The held amount can later be:
- Captured via
capture_authorization. - Released via
release_authorization. - Auto-released when the hold expires.
- Captured via
Example
If amount = "50", the ledger reserves 50 credits immediately, if available. A later capture_authorization can consume all or part of that hold. Any unused remainder is released back to the usable balance.
Unix timestamp (in seconds) representing when the business operation occurred in the upstream system.
Usage
Used for period attribution, grace-period eligibility, and reporting accuracy.
Note
Late or out-of-order submissions appear in arrival order, while attribution and eligibility logic rely on ledger_operation_timestamp.
Constraints
- The
ledger_operation_timestampmust be within the last 10 minutes from the time of the request. - Grant blocks outside their active window (including those in the grace period) are not eligible for authorization and are excluded from balance checks for this ledger operation.
Unix timestamp (in seconds) indicating when an unfinalized hold will be automatically released back to the usable balance.
Behavior
- Applies only to authorize operations.
- If not explicitly provided, the system assigns a default expiry. Defaults to approximately 10 minutes after the authorize request is processed.
Usage
Ensures held credits are not locked indefinitely by abandoned or unfinalized authorizations.
Note
- By default, the value reflects what is provided in the request.
- If the specified timestamp exceeds the end of the block's grace period, it is adjusted (clamped) to the grace period end and returned in the response.