Depositing credits

Use POST /v1/customers/deposit to add funds to a customer’s wallet.

Velobase is an AI gateway first: point your OpenAI or Anthropic SDK at https://api.velobase.io/v1 and every model call is billed to a customer’s wallet via the X-Velobase-Customer header. Deposits fund that wallet. The same wallet also backs the billing primitives (freeze, consume, deduct) for work you price yourself. See Quickstart for the gateway flow.

Minimal example

Amounts use explicit unit fields: amount_usd, amount_cents, or amount_credits, where 1 USD = 100 cents = 1,000,000 credits. Prefer amount_usd.

curl -X POST https://api.velobase.io/v1/customers/deposit \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "user_987",
    "amount_usd": 5
  }'

If the customer does not exist, it is created automatically.

Using the SDK

# pip install "velobase-billing>=0.2.1"
from velobase_billing import Velobase

vb = Velobase(api_key="your_api_key_here")
vb.customers.deposit(customer_id="user_987", amount_usd=5)
# explicit units: amount_usd / amount_cents / amount_credits
# (1 USD = 100 cents = 1,000,000 credits)

// npm i @velobaseai/billing@^1.1.1
import { Velobase } from "@velobaseai/billing";

const vb = new Velobase({ apiKey: "your_api_key_here" });
await vb.customers.deposit({ customerId: "user_987", amountUsd: 5 });
// explicit units: amountUsd / amountCents / amountCredits

Both deposits are idempotent on an idempotency key, and create the customer on first use. See the Python and JavaScript SDK references for the full surface.

Add a wallet category

Use credit_type when you want this deposit to show up under a specific wallet category in the console and wallet breakdown.

curl -X POST https://api.velobase.io/v1/customers/deposit \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "user_987",
    "amount_usd": 2.5,
    "credit_type": "promo_campaign_2026",
    "idempotency_key": "deposit_user_987_promo_2026"
  }'

Use any string for credit_type, for example: default, promo_campaign_2026, membership_gold.

Add a validity period

Use starts_at and expires_at when these funds should only be usable during a specific time window.

curl -X POST https://api.velobase.io/v1/customers/deposit \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "user_987",
    "amount_usd": 1,
    "credit_type": "summer_campaign_2026",
    "starts_at": "2026-06-01T00:00:00.000Z",
    "expires_at": "2026-06-30T23:59:59.999Z",
    "idempotency_key": "deposit_user_987_summer_campaign_2026"
  }'

Before starts_at the funds are inactive. After expires_at they are no longer counted.

Parameter reference

body.customer_id

string

required

Your internal ID for the customer. If the customer does not exist, it is created automatically.

body.amount_usd

number

Amount to add, in US dollars. Must be greater than 0. Provide exactly one amount field.

body.amount_cents

number

Amount to add, in cents (1 USD = 100 cents).

body.amount_credits

number

Amount to add, in credits (1 USD = 1,000,000 credits).

A bare amount is legacy and is interpreted as cents, not credits. Prefer the explicit amount_usd, amount_cents, or amount_credits fields.

body.credit_type

string

default:"default"

Wallet category for this deposit. Use any string, such as default, promo_campaign_2026, or membership_gold. Defaults to default.

body.starts_at

string

ISO 8601 datetime. Before this time, the deposited funds do not count toward the available wallet balance.

body.expires_at

string

ISO 8601 datetime. After this time, the deposited funds no longer count toward the available wallet balance. Must be later than starts_at.

body.idempotency_key

string

Prevents duplicate deposits. Repeating a request with the same key returns the original result with is_idempotent_replay: true and does not create a second deposit.

body.name

string

Display name for the customer. Created or updated on deposit.

body.email

string

Email address for the customer. Created or updated on deposit.

body.metadata

object

Arbitrary JSON attached to the customer record.

body.description

string

A human-readable note for this deposit.

Deposit response

{
  "customer_id": "user_987",
  "account_id": "...",
  "credit_type": "summer_campaign_2026",
  "total_amount": 1000000,
  "added_amount": 1000000,
  "starts_at": "2026-06-01T00:00:00.000Z",
  "expires_at": "2026-06-30T23:59:59.999Z",
  "record_id": "...",
  "is_idempotent_replay": false
}

customer_id

string

The customer ID passed in the request.

account_id

string

The underlying wallet source created by this deposit.

credit_type

string

Wallet category used for this deposit.

total_amount

number

Total amount, in credits, on this wallet source record. Not the customer’s overall wallet balance.

added_amount

number

Amount, in credits, added by this specific request.

starts_at

string

Start time of this wallet source’s validity window.

expires_at

string

Expiry time of this wallet source’s validity window.

record_id

string

The ledger record ID for this deposit.

is_idempotent_replay

boolean

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

Query wallet and categories

Fetch the customer to see their wallets. GET /v1/customers/{id} returns a wallets map keyed by wallet category, each with its own totals and the sources (deposits) that fund it.

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

{
  "id": "user_987",
  "name": "Alice",
  "email": "alice@example.com",
  "metadata": {},
  "wallets": {
    "default": {
      "total": 1000000,
      "used": 0,
      "frozen": 0,
      "available": 1000000,
      "sources": [
        {
          "source": "default",
          "total": 1000000,
          "used": 0,
          "frozen": 0,
          "available": 1000000,
          "starts_at": null,
          "expires_at": null
        }
      ]
    },
    "promo_campaign_2026": {
      "total": 500000,
      "used": 0,
      "frozen": 0,
      "available": 500000,
      "sources": [
        {
          "source": "promo_campaign_2026",
          "total": 500000,
          "used": 0,
          "frozen": 0,
          "available": 500000,
          "starts_at": null,
          "expires_at": null
        }
      ]
    }
  },
  "created_at": "2026-04-07T12:00:00.000Z"
}

wallets

object

Map of wallet category to that wallet’s balance. The key is the credit_type used at deposit time.

wallets.{category}.total

number

Total credits in this wallet across its active sources.

wallets.{category}.used

number

Credits already consumed from this wallet.

wallets.{category}.frozen

number

Credits currently reserved by in-progress staged deduction flows.

wallets.{category}.available

number

Credits available to spend in this wallet: total - used - frozen.

wallets.{category}.sources

array

Per-source breakdown. Each entry corresponds to one deposit, with its own validity window via starts_at and expires_at.

Error format

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

{
  "error": {
    "message": "starts_at must be a valid ISO datetime",
    "type": "bad_request",
    "code": "invalid_starts_at"
  }
}

error.message

string

Human-readable description of the error.

error.type

string

High-level error category, such as bad_request.

error.code

string

Stable machine-readable error code for programmatic handling.

​Minimal example

​Using the SDK

​Add a wallet category

​Add a validity period

​Parameter reference

​Deposit response

​Query wallet and categories

​Error format

Minimal example

Using the SDK

Add a wallet category

Add a validity period

Parameter reference

Deposit response

Query wallet and categories

Error format