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

amount is a positive integer number of credits. 1 credit = 1 micro-USD, so 1 USD = 1,000,000 credits. Unit-suffixed fields such as amount_usd, amount_cents, or amount_credits are rejected with an error.

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": 5000000,
    "idempotency_key": "dep_user_987_001"
  }'

This deposits 5,000,000 credits, which is $5.00. If the customer does not exist, it is created automatically.

Using the SDK

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

const vb = new Velobase({ apiKey: "your_api_key_here" });
await vb.customers.deposit({
  customerId: "user_987",
  amount: 5_000_000, // integer credits: $5.00
  idempotencyKey: "stripe_evt_1a2b3c",
});

Deposits are idempotent on the idempotency key, and create the customer on first use. See the JavaScript SDK reference for the full surface. From Python, call the REST endpoint directly as in the cURL examples on this page.

Deposit into a named wallet

Use wallet when you want this deposit to show up under a specific wallet in the console and wallet breakdown. The default wallet is credits.

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": 2500000,
    "wallet": "promo_campaign_2026",
    "idempotency_key": "deposit_user_987_promo_2026"
  }'

Use any string for wallet, for example: credits, 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": 1000000,
    "wallet": "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

string

required

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

number

required

Amount to add, in positive integer credits. Must be greater than 0. 1 USD = 1,000,000 credits.

Unit-suffixed fields (amount_usd, amount_cents, amount_credits) are not accepted; the API rejects them with an error. Convert to integer credits before calling.

string

default:"credits"

Wallet for this deposit. Use any string, such as credits, promo_campaign_2026, or membership_gold. Defaults to credits. (credit_type is a deprecated alias for this field.)

string

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

string

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

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. Optional, but strongly recommended: use your payment event id.

string

Display name for the customer. Used when creating a new customer.

string

Email address for the customer. Used when creating a new customer.

string

A human-readable note for this deposit.

Deposit response

{
  "customer_id": "user_987",
  "account_id": "...",
  "wallet": "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
}

string

The customer ID passed in the request.

string

The underlying wallet source created by this deposit.

string

Wallet used for this deposit.

number

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

number

Amount, in credits, added by this specific request.

string

Start time of this wallet source’s validity window.

string

Expiry time of this wallet source’s validity window.

string

The ledger record ID for this deposit.

boolean

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

Query wallets

Fetch the customer to see their wallets. GET /v1/customers/{id} returns a wallets map keyed by wallet name, 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": {
    "credits": {
      "total": 5000000,
      "used": 0,
      "frozen": 0,
      "available": 5000000,
      "sources": [
        {
          "source": "credits",
          "total": 5000000,
          "used": 0,
          "frozen": 0,
          "available": 5000000,
          "starts_at": null,
          "expires_at": null
        }
      ]
    },
    "promo_campaign_2026": {
      "total": 2500000,
      "used": 0,
      "frozen": 0,
      "available": 2500000,
      "sources": [
        {
          "source": "promo_campaign_2026",
          "total": 2500000,
          "used": 0,
          "frozen": 0,
          "available": 2500000,
          "starts_at": null,
          "expires_at": null
        }
      ]
    }
  },
  "created_at": "2026-04-07T12:00:00.000Z"
}

object

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

number

Total credits in this wallet across its active sources.

number

Credits already consumed from this wallet.

number

Credits currently reserved by in-progress staged deduction flows.

number

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

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"
  }
}

string

Human-readable description of the error.

string

High-level error category, such as bad_request.

string

Stable machine-readable error code for programmatic handling.

Getting Started

Integration Guides

Dashboard & Management

Advanced Topics

Pricing

Depositing credits

Minimal example

Using the SDK

Deposit into a named wallet

Add a validity period

Parameter reference

Deposit response

Query wallets

Error format

​Minimal example

​Using the SDK

​Deposit into a named wallet

​Add a validity period

​Parameter reference

​Deposit response

​Query wallets

​Error format

Minimal example

Using the SDK

Deposit into a named wallet

Add a validity period

Parameter reference

Deposit response

Query wallets

Error format