Staged Deduction

Use the freeze -> consume / unfreeze flow to bill work that you price yourself, when the cost is unknown upfront. This is one half of Velobase: the billing ledger for your own work. This is the right choice for async tasks, batch jobs, and any flow where the final cost is only known after execution.

If you are billing model calls, you usually do not need this flow. Point your OpenAI or Anthropic SDK at https://api.velobase.io/v1 and pass X-Velobase-Customer: <user-id>, and the gateway freezes, settles the real token cost, and deducts from the customer wallet for you on every call. See the Quickstart for the gateway path. Use staged deduction below when you price the work yourself rather than per model token.

transaction_id is the unique ID for this charge transaction and stays the same across freeze, consume, and unfreeze. All amount fields are positive integer credits. 1 credit = 1 micro-USD, so 1 USD = 1,000,000 credits.

Freeze

Reserve a maximum budget before starting work. After freezing, the funds are no longer available to spend, but they have not been consumed yet.

curl -X POST https://api.velobase.io/v1/billing/freeze \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "user_987",
    "transaction_id": "llm_chat_001",
    "amount": 1000000
  }'

This freezes 1,000,000 credits, which is $1.00.Freeze Parameters

string

required

The unique identifier for this customer. The customer must already exist and have enough available funds in their wallet to cover the freeze amount.

string

required

Unique ID for this charge transaction. Use the same value for the subsequent consume or unfreeze call.

number

required

Maximum amount to reserve, in integer credits (1 USD = 1,000,000 credits). Must be greater than 0. Set this to the upper bound of expected cost.

string

Optional. Restrict the freeze to a single wallet by name. If omitted, the system may use any active funds. The same wallet is used automatically during consume.

string

Transaction category for reporting. Examples: TASK, ORDER, TOKEN_USAGE.

number

Optional TTL. If the transaction is never settled, the frozen credits are automatically released back to the wallet after this many seconds. Use it so a crashed worker cannot strand a customer’s funds forever.

number

Optional TTL. If the transaction is never settled, the frozen credits are automatically consumed after this many seconds.

string

A human-readable note for this freeze.

Freeze Response

{
  "transaction_id": "llm_chat_001",
  "frozen_amount": 1000000,
  "freeze_details": [
    {
      "account_id": "...",
      "credit_type": "credits",
      "amount": 1000000
    }
  ],
  "is_idempotent_replay": false
}

string

The transaction ID passed in the request.

number

Total credits reserved by this freeze.

array

Breakdown of which wallet sources were frozen. The system may freeze across multiple wallet sources.

Show freeze_details properties

string

Underlying wallet source ID that was frozen.

string

Wallet that was frozen.

number

Credits frozen from that source.

boolean

true when the response was returned from a previous request with the same transaction_id.

Returns an insufficient_balance error if the customer wallet does not have enough available funds.

Consume

Settle the actual cost after the task finishes. Any unused funds are returned automatically.

curl -X POST https://api.velobase.io/v1/billing/consume \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "transaction_id": "llm_chat_001",
    "actual_amount": 730000
  }'

Example: freeze 1000000 credits (

1.00), finish with an actual cost of `730000` credits (

0.73), and the remaining 270000 credits ($0.27) are automatically returned.Consume Parameters

string

required

The same transaction ID used in the freeze step.

number

Actual credits to consume. If less than the frozen amount, the remainder is returned. Defaults to the full frozen amount if omitted.

Consume Response

{
  "transaction_id": "llm_chat_001",
  "consumed_amount": 730000,
  "returned_amount": 270000,
  "consume_details": [
    {
      "account_id": "...",
      "credit_type": "credits",
      "amount": 730000
    }
  ],
  "consumed_at": "2026-04-07T12:00:00.000Z",
  "is_idempotent_replay": false
}

number

Credits permanently consumed by this operation.

number

Unused frozen credits automatically returned to the available wallet balance (frozen_amount - actual_amount).

array

Breakdown of which wallet sources were consumed.

Show consume_details properties

string

Underlying wallet source ID that was consumed.

string

Wallet that was consumed.

number

Credits consumed from that source.

string

ISO 8601 timestamp when consumption completed.

boolean

true when the response was returned from a previous request with the same transaction_id.

Unfreeze (Cancel)

Release frozen funds without consuming. Use when the task is cancelled.

curl -X POST https://api.velobase.io/v1/billing/unfreeze \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "transaction_id": "llm_chat_001"
  }'

Unfreeze Response

{
  "transaction_id": "llm_chat_001",
  "unfrozen_amount": 1000000,
  "unfreeze_details": [
    {
      "account_id": "...",
      "credit_type": "credits",
      "amount": 1000000
    }
  ],
  "unfrozen_at": "2026-04-07T12:01:00.000Z",
  "is_idempotent_replay": false
}

number

Total credits returned to the available wallet balance.

array

Breakdown of which wallet sources were unfrozen.

Show unfreeze_details properties

string

Underlying wallet source ID that was unfrozen.

string

Wallet that was unfrozen.

number

Credits released from that source.

string

ISO 8601 timestamp when the unfreeze completed.

boolean

true when the response was returned from a previous request with the same transaction_id.

Timeouts (TTL)

A freeze does not have to stay open forever. Two optional freeze parameters bound its lifetime:

unfreeze_after_seconds: if you never call consume or unfreeze, the reservation auto-releases and the credits return to the customer.
consume_after_seconds: if you never settle, the frozen amount is auto-consumed instead.

Pick one based on who should bear the cost of an abandoned transaction. If neither is set, the freeze stays open until you settle it.

Wallets and Consumption Order

The system automatically freezes and consumes from all available wallet funds.
If wallet is provided during freeze, only that wallet is eligible for this transaction.
Callers do not choose the underlying funding sources.
Funds that expire sooner are handled first. If expiry is the same, older sources are handled first.
Only funds that are currently active participate in freeze and consume. Funds that have not started yet or have already expired are ignored.
Use the customer API to inspect remaining funds per wallet source.

Idempotency

All three operations are idempotent on transaction_id. Duplicate calls return the original result with is_idempotent_replay: true.

Verify the Result

Fetch the customer to inspect their wallets:

curl https://api.velobase.io/v1/customers/user_987 \
  -H "Authorization: Bearer your_api_key_here"

{
  "id": "user_987",
  "name": "Ada Lovelace",
  "email": "ada@example.com",
  "metadata": {},
  "wallets": {
    "credits": {
      "total": 10000000,
      "used": 730000,
      "frozen": 0,
      "available": 9270000,
      "sources": [
        {
          "source": "deposit",
          "total": 10000000,
          "used": 730000,
          "frozen": 0,
          "available": 9270000,
          "starts_at": null,
          "expires_at": null
        }
      ]
    }
  },
  "created_at": "2026-04-07T11:00:00.000Z"
}

After each step, check the wallets["credits"] summary:

whether frozen increases after freeze
whether used increases after consume
whether available changes as expected
which wallet sources[] were used

All wallet amounts are in integer credits (1 USD = 1,000,000 credits).

Error Format

All API errors return an HTTP error status and a structured error object:

{
  "error": {
    "message": "freeze record not found",
    "type": "not_found",
    "code": "freeze_record_not_found"
  }
}

string

Human-readable description of the error.

string

High-level error category.

string

Stable machine-readable error code for programmatic handling.

Getting Started

Integration Guides

Dashboard & Management

Advanced Topics

Pricing

Timeouts (TTL)

Wallets and Consumption Order

Idempotency

Verify the Result

Error Format

​Timeouts (TTL)

​Wallets and Consumption Order

​Idempotency

​Verify the Result

​Error Format

Timeouts (TTL)

Wallets and Consumption Order

Idempotency

Verify the Result

Error Format