# Capture

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


The capture operation immediately consumes credits for a completed action.

**Behavior**

-   Credits are directly moved from usable → consumed.
-   No intermediate hold or reservation is created.

**Usage**

Ideal for simple, immediate consumption scenarios where there is no need for multi-step confirmation or concurrency control.

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/capture \
     -u {site_api_key}:\
     --header 'Content-Type: application/json;charset=UTF-8' \
     --data '{
     "subscription_id": "1mGETgZVF2umUZq",
     "unit_id": "ai_credits",
     "amount": "10.35",
     "ledger_operation_timestamp": 1774978590,
     "id": "tu80phup1"
}'
```

#### .NET

```dotnet
using ChargeBee.Api;
using ChargeBee.Models;

ApiConfig.Configure("{site}","{site_api_key}");
EntityResult result = LedgerOperation.Capture()
		.SubscriptionId("1mGETgZVF2umUZq")
		.UnitId("ai_credits")
		.Amount("10.35")
		.LedgerOperationTimestamp(1774978590)
		.Id("tu80phup1")
		.Request();

LedgerOperation ledgerOperation = result.LedgerOperation;
List<LedgerOperation> ledgerOperations = result.LedgerOperations;
LedgerAccountBalance ledgerAccountBalance = result.LedgerAccountBalance;
List<GrantBlock> grantBlocks = result.GrantBlocks;
List<LedgerEntry> 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.Capture(&ledgeroperation.CaptureRequestParams{
        SubscriptionId : "1mGETgZVF2umUZq",
        UnitId : "ai_credits",
        Amount : "10.35",
        LedgerOperationTimestamp : chargebee.Int64(1774978590),
        Id : "tu80phup1",
    }).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.LedgerOperationCaptureRequest{
    SubscriptionId : "1mGETgZVF2umUZq",
    UnitId : "ai_credits",
    Amount : "10.35",
    LedgerOperationTimestamp : chargebee.Int64(1774978590),
    Id : "tu80phup1",
}
  res, err := client.LedgerOperation.Capture(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.capture()
            .subscriptionId("1mGETgZVF2umUZq")
            .unitId("ai_credits")
            .amount("10.35")
            .ledgerOperationTimestamp(new Timestamp(1774978590L * 1000))
            .id("tu80phup1")
            .request();

        LedgerOperation ledgerOperation = result.ledgerOperation();
        List<LedgerOperation> ledgerOperations = result.ledgerOperations();
        LedgerAccountBalance ledgerAccountBalance = result.ledgerAccountBalance();
        List<GrantBlock> grantBlocks = result.grantBlocks();
        List<LedgerEntry> 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.LedgerOperationCaptureParams;
import com.chargebee.v4.models.ledgerOperation.responses.LedgerOperationCaptureResponse;
import java.sql.Timestamp;
import java.util.List;

public class LedgerOperationCapture {

    public static void main(String[] args) {
        ChargebeeClient client = ChargebeeClient.builder()
            .apiKey("{site_api_key}")
            .siteName("{site}")
            .build();

        LedgerOperationCaptureParams params = LedgerOperationCaptureParams.builder()
            .subscriptionId("1mGETgZVF2umUZq")
            .unitId("ai_credits")
            .amount("10.35")
            .ledgerOperationTimestamp(new Timestamp(1774978590L * 1000))
            .id("tu80phup1")
            .build();

        LedgerOperationCaptureResponse response = client.ledgerOperations().capture(params);

        LedgerOperation ledgerOperation = response.getLedgerOperation();
        List<LedgerOperation> ledgerOperations = response.getLedgerOperations();
        LedgerAccountBalance ledgerAccountBalance = response.getLedgerAccountBalance();
        List<GrantBlock> grantBlocks = response.getGrantBlocks();
        List<LedgerEntry> 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.capture({
        subscription_id: "1mGETgZVF2umUZq",
        unit_id: "ai_credits",
        amount: "10.35",
        ledger_operation_timestamp: 1774978590,
        id: "tu80phup1"
    });

    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
<?php

require __DIR__ . '/vendor/autoload.php';

use Chargebee\ChargebeeClient;

$chargebee = new ChargebeeClient(options: [
    "site" => "{site}",
    "apiKey" => "{site_api_key}",
]);
$result = $chargebee->ledgerOperation()->capture([
    "subscription_id" => "1mGETgZVF2umUZq",
    "unit_id" => "ai_credits",
    "amount" => "10.35",
    "ledger_operation_timestamp" => 1774978590,
    "id" => "tu80phup1"
]);
$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.capture(
    cb_client.LedgerOperation.CaptureParams(
        subscription_id="1mGETgZVF2umUZq",
        unit_id="ai_credits",
        amount="10.35",
        ledger_operation_timestamp=1774978590,
        id="tu80phup1"
    )
)
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.capture({
  :subscription_id => "1mGETgZVF2umUZq",
  :unit_id => "ai_credits",
  :amount => "10.35",
  :ledger_operation_timestamp => 1774978590,
  :id => "tu80phup1"
})

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": "tu80phup1",
      "subscription_id": "1mGETgZVF2umUZq",
      "unit_id": "ai_credits",
      "unit_type": "credit_unit",
      "type": "capture",
      "amount": "10.35",
      "provisioned_start_balance": "100.25",
      "provisioned_end_balance": "89.9",
      "overdraft_start_balance": "20",
      "overdraft_end_balance": "20",
      "ledger_operation_timestamp": 1774978590,
      "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": "89.9",
      "usable_balance": "89.9",
      "hold_amount": "0"
    },
    "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": "89.9",
        "usable_balance": "89.9",
        "hold_amount": "0",
        "used_amount": "10.35",
        "expired_amount": "0",
        "rolled_over_amount": "0",
        "voided_amount": "0"
      },
      "overdraft_block_balance": null
    },
    {..}
  ],
  "ledger_entries": [
    {
      "id": "le_capture_001",
      "subscription_id": "1mGETgZVF2umUZq",
      "unit_id": "ai_credits",
      "unit_type": "credit_unit",
      "account_type": "provisioned",
      "amount": "10.35",
      "grant_block_start_balance": "100.25",
      "grant_block_end_balance": "89.9",
      "account_start_balance": "100.25",
      "account_end_balance": "89.9",
      "type": "debit",
      "ledger_operation_id": "tu80phup1",
      "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/capture

## Input Parameters

- `id` (optional, string, max chars=50)
  Optional client-supplied identifier for this capture operation.
  
  **Behavior**
  
  -   When provided, must uniquely identify this operation across the entire ledger.
  -   Should not conflict with any other operation, regardless of type.

- `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 credits to immediately consume from the usable balance. 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**
  
  Credits are directly moved from usable → consumed as part of this operation.
  
  **Constraints**
  
  -   Must be a positive value.
  -   Evaluated against the current usable balance at the time of processing.
  
  **Example**
  
  If `amount = "50"`, then 50 credits are immediately deducted from the usable balance and recorded as consumed.

- `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`.

- `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 capture. Retained for backward compatibility.

- `ledger_operations` (always returned)
  The resulting [`ledger_operations`](/docs/api/ledger_operations) for this capture. 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) for the requested subscription and unit after this capture, 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 `debit` that make up this capture.