Direct Deduction

Use POST /v1/billing/deduct to deduct from a customer’s available wallet balance in a single request. This is the right choice for fixed-price image generation, fixed-cost API calls, and other one-time operations where cost is known upfront. It is one of the billing primitives you use for work you price yourself.

Model calls you route through the Velobase AI gateway (POST /v1/chat/completions, POST /v1/messages) bill the customer wallet automatically at real token cost. You do not need to call deduct for those. Use direct deduction for your own priced work. See the gateway quickstart for routing model calls.

If cost is unknown in advance, or you need to reserve funds before settlement, use staged deduction instead.

Minimal Example

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

This deducts 50,000 credits, which is $0.05 (1 USD = 1,000,000 credits).

Parameters

string

required

The unique identifier for this customer. The customer must already exist and have enough available balance in their wallet.

string

required

Unique ID for this charge transaction. Also serves as the idempotency key: repeating a request with the same transaction_id returns the original result without double-charging.

number

required

Amount to deduct, in positive integer credits. Must be greater than 0. 1 credit = 1 micro-USD, so 1 USD = 1,000,000 credits. Explicit unit fields such as amount_usd, amount_cents, or amount_credits are rejected.

string

Optional. Restrict the deduction to a single wallet by name. If omitted, the system may draw from any active credits.

string

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

string

A human-readable note for this transaction.

Response

{
  "transaction_id": "img_gen_001",
  "deducted_amount": 50000,
  "deduct_details": [
    {
      "account_id": "...",
      "credit_type": "credits",
      "amount": 50000
    }
  ],
  "deducted_at": "2026-04-07T12:00:00.000Z",
  "is_idempotent_replay": false
}

string

The unique transaction ID passed in the request.

number

Total amount actually deducted, in credits (1,000,000 credits = 1 USD).

array

Deduction breakdown. Funds may be consumed from multiple wallet sources when the amount spans more than one source.

Show deduct_details properties

string

Underlying funding source ID used for the deduction.

string

Wallet that was consumed.

number

Amount deducted from that source, in credits.

string

ISO 8601 timestamp when the deduction completed.

boolean

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

Deduction Rules and Wallets

The system automatically deducts from all available balance across the customer’s wallets.
If wallet is provided, deduction is limited to that wallet only.
Callers do not choose which underlying funding source is consumed.
Funds that expire sooner are consumed first. If expiry is the same, older sources are consumed first.
Only funds that are currently active are eligible for deduction. Sources that have not started yet or have already expired are ignored.
Use GET /v1/customers/{id} to inspect the remaining balance per wallet and per source.

Insufficient Balance

Returns an insufficient_balance error if the customer doesn’t have enough available balance:

{
  "error": {
    "message": "insufficient balance",
    "type": "bad_request",
    "code": "insufficient_balance"
  }
}

Failed requests do not produce a partial deduction and do not leave behind a half-completed state.

Idempotency

Same transaction_id returns the same result, with is_idempotent_replay: true and no double charge.

Verify the Result

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

GET /v1/customers/{id} returns the customer with a wallets map. Each wallet reports total, used, frozen, and available, plus a sources array broken down by funding source:

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

After deduction, check:

whether the wallet’s available decreased (values are in credits, where 1,000,000 credits = 1 USD)
which sources[] entries were consumed
whether each sources[].available value changed as expected

Error Format

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

{
  "error": {
    "message": "insufficient balance",
    "type": "bad_request",
    "code": "insufficient_balance"
  }
}

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

Minimal Example

Parameters

Response

Deduction Rules and Wallets

Insufficient Balance

Idempotency

Verify the Result

Error Format

​Minimal Example

​Parameters

​Response

​Deduction Rules and Wallets

​Insufficient Balance

​Idempotency

​Verify the Result

​Error Format

Minimal Example

Parameters

Response

Deduction Rules and Wallets

Insufficient Balance

Idempotency

Verify the Result

Error Format