# Authorize > For the complete machine-readable documentation index, see [llms.txt](https://apidocs.chargebee.com/llms.txt). 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 `ledger_operations` (and, for compatibility, a deprecated singular `ledger_operation`), the updated `ledger_account_balance`, the affected `grant_blocks`, and the `ledger_entries` recorded by this operation. ## Sample Request #### cURL ```bash curl https://{site}.chargebee.com/api/v2/ledger_operations/authorize \ -u {site_api_key}:\ --header 'Content-Type: application/json;charset=UTF-8' \ --data '{ "subscription_id": "1mGETgZVF2umUZq", "unit_id": "ai_credits", "amount": "50.5", "ledger_operation_timestamp": 1774978590, "auto_release_timestamp": 1774978659, "id": "eyexnp6sc" }' ``` #### .NET ```dotnet using ChargeBee.Api; using ChargeBee.Models; ApiConfig.Configure("{site}","{site_api_key}"); EntityResult result = LedgerOperation.Authorize() .SubscriptionId("1mGETgZVF2umUZq") .UnitId("ai_credits") .Amount("50.5") .LedgerOperationTimestamp(1774978590) .AutoReleaseTimestamp(1774978659) .Id("eyexnp6sc") .Request(); LedgerOperation ledgerOperation = result.LedgerOperation; List ledgerOperations = result.LedgerOperations; LedgerAccountBalance ledgerAccountBalance = result.LedgerAccountBalance; List grantBlocks = result.GrantBlocks; List ledgerEntries = result.LedgerEntries; ``` #### Go ```go package main import ( "fmt" "github.com/chargebee/chargebee-go/v3" ledgeroperationAction "github.com/chargebee/chargebee-go/v3/actions/ledgeroperation" "github.com/chargebee/chargebee-go/v3/models/ledgeroperation" ) func main() { chargebee.Configure("{site_api_key}","{site}"); res,err := ledgeroperationAction.Authorize(&ledgeroperation.AuthorizeRequestParams{ SubscriptionId : "1mGETgZVF2umUZq", UnitId : "ai_credits", Amount : "50.5", LedgerOperationTimestamp : chargebee.Int64(1774978590), AutoReleaseTimestamp : chargebee.Int64(1774978659), Id : "eyexnp6sc", }).Request() if err != nil { fmt.Println(err) } else { LedgerOperation := res.LedgerOperation LedgerOperations := res.LedgerOperations LedgerAccountBalance := res.LedgerAccountBalance GrantBlocks := res.GrantBlocks LedgerEntries := res.LedgerEntries } } ``` #### Go ```go package main import ( "fmt" "github.com/chargebee/chargebee-go/v4" ) func main() { config := &chargebee.ClientConfig{ SiteName: "{site}", ApiKey: "{site_api_key}", } client := chargebee.NewClient(config) req := &chargebee.LedgerOperationAuthorizeRequest{ SubscriptionId : "1mGETgZVF2umUZq", UnitId : "ai_credits", Amount : "50.5", LedgerOperationTimestamp : chargebee.Int64(1774978590), AutoReleaseTimestamp : chargebee.Int64(1774978659), Id : "eyexnp6sc", } res, err := client.LedgerOperation.Authorize(req) if err != nil { fmt.Println(err) } else { LedgerOperation := res.LedgerOperation LedgerOperations := res.LedgerOperations LedgerAccountBalance := res.LedgerAccountBalance GrantBlocks := res.GrantBlocks LedgerEntries := res.LedgerEntries } } ``` #### Java ```java import com.chargebee.*; import com.chargebee.ListResult; import com.chargebee.models.*; import com.chargebee.models.enums.*; import java.io.IOException; import java.util.List; import java.sql.Timestamp; public class Sample { public static void main(String args[]) throws IOException, Exception { Environment.configure("{site}", "{site_api_key}"); Result result = LedgerOperation.authorize() .subscriptionId("1mGETgZVF2umUZq") .unitId("ai_credits") .amount("50.5") .ledgerOperationTimestamp(new Timestamp(1774978590L * 1000)) .autoReleaseTimestamp(new Timestamp(1774978659L * 1000)) .id("eyexnp6sc") .request(); LedgerOperation ledgerOperation = result.ledgerOperation(); List ledgerOperations = result.ledgerOperations(); LedgerAccountBalance ledgerAccountBalance = result.ledgerAccountBalance(); List grantBlocks = result.grantBlocks(); List ledgerEntries = result.ledgerEntries(); } } ``` #### Java ```java import com.chargebee.v4.client.ChargebeeClient; import com.chargebee.v4.models.grantBlock.GrantBlock; import com.chargebee.v4.models.ledgerAccountBalance.LedgerAccountBalance; import com.chargebee.v4.models.ledgerEntry.LedgerEntry; import com.chargebee.v4.models.ledgerOperation.LedgerOperation; import com.chargebee.v4.models.ledgerOperation.LedgerOperation; import com.chargebee.v4.models.ledgerOperation.params.LedgerOperationAuthorizeParams; import com.chargebee.v4.models.ledgerOperation.responses.LedgerOperationAuthorizeResponse; import java.sql.Timestamp; import java.util.List; public class LedgerOperationAuthorize { public static void main(String[] args) { ChargebeeClient client = ChargebeeClient.builder() .apiKey("{site_api_key}") .siteName("{site}") .build(); LedgerOperationAuthorizeParams params = LedgerOperationAuthorizeParams.builder() .subscriptionId("1mGETgZVF2umUZq") .unitId("ai_credits") .amount("50.5") .ledgerOperationTimestamp(new Timestamp(1774978590L * 1000)) .autoReleaseTimestamp(new Timestamp(1774978659L * 1000)) .id("eyexnp6sc") .build(); LedgerOperationAuthorizeResponse response = client.ledgerOperations().authorize(params); LedgerOperation ledgerOperation = response.getLedgerOperation(); List ledgerOperations = response.getLedgerOperations(); LedgerAccountBalance ledgerAccountBalance = response.getLedgerAccountBalance(); List grantBlocks = response.getGrantBlocks(); List ledgerEntries = response.getLedgerEntries(); } } ``` #### Node.js ```node import Chargebee from "chargebee"; const chargebee = new Chargebee({ site: "{site}", apiKey: "{site_api_key}", }); try { const result = await chargebee.ledgerOperation.authorize({ subscription_id: "1mGETgZVF2umUZq", unit_id: "ai_credits", amount: "50.5", ledger_operation_timestamp: 1774978590, auto_release_timestamp: 1774978659, id: "eyexnp6sc" }); console.log(result); const ledgerOperation = result.ledger_operation; const ledgerOperations = result.ledger_operations; const ledgerAccountBalance = result.ledger_account_balance; const grantBlocks = result.grant_blocks; const ledgerEntries = result.ledger_entries; } catch (err) { console.log(err); } ``` #### PHP ```php "{site}", "apiKey" => "{site_api_key}", ]); $result = $chargebee->ledgerOperation()->authorize([ "subscription_id" => "1mGETgZVF2umUZq", "unit_id" => "ai_credits", "amount" => "50.5", "ledger_operation_timestamp" => 1774978590, "auto_release_timestamp" => 1774978659, "id" => "eyexnp6sc" ]); $ledgerOperation = $result->ledger_operation; $ledgerOperations = $result->ledger_operations; $ledgerAccountBalance = $result->ledger_account_balance; $grantBlocks = $result->grant_blocks; $ledgerEntries = $result->ledger_entries; ``` #### Python ```python from chargebee import Chargebee cb_client = Chargebee(api_key="{site_api_key}", site="{site}") response = cb_client.LedgerOperation.authorize( cb_client.LedgerOperation.AuthorizeParams( subscription_id="1mGETgZVF2umUZq", unit_id="ai_credits", amount="50.5", ledger_operation_timestamp=1774978590, auto_release_timestamp=1774978659, id="eyexnp6sc" ) ) ledger_operation = response.ledger_operation ledger_operations = response.ledger_operations ledger_account_balance = response.ledger_account_balance grant_blocks = response.grant_blocks ledger_entries = response.ledger_entries ``` #### Ruby ```ruby require 'chargebee' ChargeBee.configure(:site => "{site}", :api_key => "{site_api_key}") result = ChargeBee::LedgerOperation.authorize({ :subscription_id => "1mGETgZVF2umUZq", :unit_id => "ai_credits", :amount => "50.5", :ledger_operation_timestamp => 1774978590, :auto_release_timestamp => 1774978659, :id => "eyexnp6sc" }) ledger_operation = result.ledger_operation ledger_operations = result.ledger_operations ledger_account_balance = result.ledger_account_balance grant_blocks = result.grant_blocks ledger_entries = result.ledger_entries ``` ## Sample Response ```json { "ledger_operations": [ { "id": "eyexnp6sc", "subscription_id": "1mGETgZVF2umUZq", "unit_id": "ai_credits", "unit_type": "credit_unit", "type": "authorize", "amount": "50.4525", "provisioned_start_balance": "100.25", "provisioned_end_balance": "100.25", "overdraft_start_balance": "20", "overdraft_end_balance": "20", "ledger_operation_timestamp": 1774978590, "auto_release_timestamp": 1774978659, "created_at": 1774978599, "modified_at": 1774978599, "object": "ledger_operation" }, {..} ], "ledger_account_balance": { "subscription_id": "1mGETgZVF2umUZq", "unit_id": "ai_credits", "unit_type": "credit_unit", "created_at": 1746723600, "modified_at": 1774978599, "resource_version": 1774978599000, "provisioned_balance": { "total_balance": "100.25", "usable_balance": "49.7975", "hold_amount": "50.4525" }, "overdraft_balance": { "is_unlimited": false, "limit": "20", "total_balance": "20", "usable_balance": "20", "used_amount": "0", "hold_amount": "0" }, "object": "ledger_account_balance" }, "grant_blocks": [ { "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 }, {..} ], "ledger_entries": [ { "id": "le_authorize_001", "subscription_id": "1mGETgZVF2umUZq", "unit_id": "ai_credits", "unit_type": "credit_unit", "account_type": "provisioned", "amount": "50.4525", "grant_block_start_balance": "100.25", "grant_block_end_balance": "100.25", "account_start_balance": "100.25", "account_end_balance": "100.25", "type": "hold", "ledger_operation_id": "eyexnp6sc", "grant_block_id": "gb_ai_credits_001", "created_at": 1774978599, "modified_at": 1774978599, "object": "ledger_entry" }, {..} ] } ``` ## URL Format **POST** https://[site].chargebee.com/api/v2/ledger_operations/authorize ## Input Parameters - `id` (optional, string, max chars=50) 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. - `subscription_id` (required, string, max chars=50) A unique, immutable identifier for the [subscription](/docs/api/subscriptions/subscription-object#id) against which credit grants are tracked. - `unit_id` (required, string, max chars=50) Identifier of the credit unit for which credit grants are tracked. For example, a credit unit id such as `ai_credits`. - `amount` (required, string, max chars=36) 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. **Constraints** 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 from `usable_balance` to `hold_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. **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. - `ledger_operation_timestamp` (required, timestamp(UTC) in seconds) 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_timestamp` must 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. - `auto_release_timestamp` (optional, timestamp(UTC) in seconds) 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. - `metadata` (optional, jsonobject) Optional opaque JSON object carrying additional business context **Behavior** - Stored as-is and returned verbatim by the system. - Not interpreted, validated, or indexed by the system. ## Returns - `ledger_operation` (Ledger operation object) **Deprecated.** Use [`ledger_operations`](#ledger_operations) instead. The single [`ledger_operation`](/docs/api/ledger_operations) resulting from this authorize (hold). Retained for backward compatibility. - `ledger_operations` (always returned) The resulting [`ledger_operations`](/docs/api/ledger_operations) for this authorize (hold). Array of one or more ledger operations. - `ledger_account_balance` (Ledger account balance object) Summarized real-time [`ledger_account_balance`](/docs/api/ledger_account_balances) after this authorize, bundling the [`provisioned_balance`](/docs/api/ledger_account_balances#provisioned_balance) and [`overdraft_balance`](/docs/api/ledger_account_balances#overdraft_balance) for the requested unit. - `grant_blocks` (always returned) The [`grant_blocks`](/docs/api/grant_blocks) affected by this operation, each reflecting its updated balances after the operation. - `ledger_entries` (always returned) The [`ledger_entries`](/docs/api/ledger_entries) recorded by this operation — immutable, per-grant-block movements of type `hold` that make up this authorization.