Endpoints

The Velobase API is organized around REST. It accepts JSON-encoded request bodies and returns JSON-encoded responses. Base URL: https://api.velobase.io

Customers

Get customer balance

Retrieve a customer’s total, frozen, and available balances, along with a detailed breakdown of all their wallet categories (accounts). GET /v1/customers/:customer_id

Path parameters

customer_id

string

required

The unique identifier for this customer in your system.

Response fields

string

The customer identifier.

name

string

The customer’s display name.

string

The customer’s email address.

balance

object

Aggregated balance totals across all wallets.

Show properties

total

number

Total credits ever deposited.

used

number

Credits that have been consumed.

frozen

number

Credits currently reserved for an in-progress task.

available

number

Credits immediately available to spend.

accounts

array

Per-wallet breakdown. Each element represents one wallet category.

Show properties

account_type

string

The account type (e.g., "CREDIT").

credit_type

string

The wallet category label.

total

number

Total credits in this wallet.

used

number

Consumed credits in this wallet.

frozen

number

Frozen credits in this wallet.

available

number

Available credits in this wallet.

starts_at

string | null

ISO 8601 datetime. Credits are inactive before this date, or null if not set.

expires_at

string | null

ISO 8601 datetime. Credits expire after this date, or null if not set.

created_at

string

ISO 8601 datetime when this customer record was created.

Example request

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

Example response

{
  "id": "user_987",
  "name": "Alice",
  "email": "alice@example.com",
  "balance": {
    "total": 1500,
    "used": 0,
    "frozen": 0,
    "available": 1500
  },
  "accounts": [
    {
      "account_type": "CREDIT",
      "credit_type": "default",
      "total": 1500,
      "used": 0,
      "frozen": 0,
      "available": 1500,
      "starts_at": null,
      "expires_at": null
    }
  ],
  "created_at": "2026-04-07T12:00:00.000Z"
}

Billing & credits

Deposit credits

Add credits to a customer’s account. If the customer does not exist yet, Velobase automatically creates them using the name and email fields you provide. POST /v1/billing/deposit

Request parameters

customer_id

string

required

The unique identifier for this customer in your system.

amount

number

required

Positive integer amount to deposit.

idempotency_key

string

required

Unique identifier for this deposit to prevent double processing.

credit_type

string

The wallet category. Defaults to "default".

starts_at

string

ISO 8601 datetime. Credits are ignored before this date.

expires_at

string

ISO 8601 datetime. Credits are ignored after this date.

name

string

Customer’s display name. Used only when creating a new customer.

string

Customer’s email address. Used only when creating a new customer.

description

string

Optional note for the ledger.

Response fields

customer_id

string

The customer identifier.

account_id

string

The wallet (account) that received the credits.

credit_type

string

The wallet category.

total_amount

number

Total credits in this wallet after the deposit.

added_amount

number

Credits added in this operation.

starts_at

string | null

ISO 8601 credit activation date, if set.

expires_at

string | null

ISO 8601 credit expiry date, if set.

record_id

string

The unique ledger record ID.

is_idempotent_replay

boolean

true if this was a duplicate request that returned the original result.

Example request

curl -X POST https://api.velobase.io/v1/billing/deposit \
  -H "Authorization: Bearer vb_1234567890abcdef" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "user_987",
    "amount": 1000,
    "idempotency_key": "dep_unique_001"
  }'

Example response

{
  "customer_id": "user_987",
  "account_id": "acc_abc123",
  "credit_type": "default",
  "total_amount": 1000,
  "added_amount": 1000,
  "starts_at": null,
  "expires_at": null,
  "record_id": "rec_xyz789",
  "is_idempotent_replay": false
}

Direct deduct

Atomically deduct credits from a customer’s available balance in a single step. Use this for immediate, one-shot charges where you do not need to reserve credits first. POST /v1/billing/deduct

Request parameters

customer_id

string

required

The unique identifier for this customer in your system.

amount

number

required

Positive integer amount to deduct.

transaction_id

string

required

Unique identifier for this task or job.

credit_types

string[]

Whitelist of wallet categories to deduct from.

description

string

Optional note for the ledger.

Response fields

transaction_id

string

Echo of the request identifier.

deducted_amount

number

Total credits deducted.

deduct_details

array

Breakdown by wallet. Each item contains account_id, credit_type, and amount.

deducted_at

string

ISO 8601 timestamp of the deduction.

is_idempotent_replay

boolean

true if this was a duplicate request.

Example request

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

Example response

{
  "transaction_id": "task_001",
  "deducted_amount": 200,
  "deduct_details": [
    {
      "account_id": "acc_abc123",
      "credit_type": "default",
      "amount": 200
    }
  ],
  "deducted_at": "2026-04-08T10:30:00.000Z",
  "is_idempotent_replay": false
}

Freeze credits

Reserve a specific amount of credits for an ongoing task. Frozen credits are held exclusively for that task and cannot be spent by any other operation until they are consumed or unfrozen. POST /v1/billing/freeze

Request parameters

customer_id

string

required

The unique identifier for this customer in your system.

amount

number

required

Positive integer amount to freeze.

transaction_id

string

required

Unique identifier for this task or job.

credit_types

string[]

Whitelist of wallet categories to freeze from.

description

string

Optional note for the ledger.

Response fields

transaction_id

string

Echo of the request identifier.

frozen_amount

number

Total credits frozen.

freeze_details

array

Breakdown by wallet. Each item contains account_id, credit_type, and amount.

is_idempotent_replay

boolean

true if this was a duplicate request.

Example request

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

Example response

{
  "transaction_id": "task_002",
  "frozen_amount": 500,
  "freeze_details": [
    {
      "account_id": "acc_abc123",
      "credit_type": "default",
      "amount": 500
    }
  ],
  "is_idempotent_replay": false
}

Consume frozen credits

Permanently deduct credits from a previously frozen transaction. You supply the actual amount used — which may be less than what was originally frozen — and Velobase returns any remainder to the customer’s available balance. POST /v1/billing/consume

Request parameters

transaction_id

string

required

The transaction_id used in the original freeze call.

actual_amount

number

required

Positive integer amount to actually deduct. Must be less than or equal to the originally frozen amount.

Response fields

transaction_id

string

Echo of the request identifier.

consumed_amount

number

Credits permanently deducted from the frozen amount.

returned_amount

number

Unused credits returned to the available balance (frozen - consumed).

consume_details

array

Breakdown by wallet. Each item contains account_id, credit_type, and amount.

consumed_at

string

ISO 8601 timestamp of the consumption.

is_idempotent_replay

boolean

true if this was a duplicate request.

Example request

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

Example response

{
  "transaction_id": "task_002",
  "consumed_amount": 300,
  "returned_amount": 200,
  "consume_details": [
    {
      "account_id": "acc_abc123",
      "credit_type": "default",
      "amount": 300
    }
  ],
  "consumed_at": "2026-04-08T10:35:00.000Z",
  "is_idempotent_replay": false
}

Unfreeze credits

Release all unused frozen credits back to the customer’s available balance. Use this when a task is canceled or fails and you want to return the reserved credits without consuming any. POST /v1/billing/unfreeze

Request parameters

transaction_id

string

required

The transaction_id used in the original freeze call.

Response fields

transaction_id

string

Echo of the request identifier.

unfrozen_amount

number

Total credits released back to the available balance.

unfreeze_details

array

Breakdown by wallet. Each item contains account_id, credit_type, and amount.

unfrozen_at

string

ISO 8601 timestamp of the unfreeze.

is_idempotent_replay

boolean

true if this was a duplicate request.

Example request

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

Example response

{
  "transaction_id": "task_002",
  "unfrozen_amount": 500,
  "unfreeze_details": [
    {
      "account_id": "acc_abc123",
      "credit_type": "default",
      "amount": 500
    }
  ],
  "unfrozen_at": "2026-04-08T10:40:00.000Z",
  "is_idempotent_replay": false
}

Overview

​Customers

​Get customer balance

​Path parameters

​Response fields

​Example request

​Example response

​Billing & credits

​Deposit credits

​Request parameters

​Response fields

​Example request

​Example response

​Direct deduct

​Request parameters

​Response fields

​Example request

​Example response

​Freeze credits

​Request parameters

​Response fields

​Example request

​Example response

​Consume frozen credits

​Request parameters

​Response fields

​Example request

​Example response

​Unfreeze credits

​Request parameters

​Response fields

​Example request

​Example response

Customers

Get customer balance

Path parameters

Response fields

Example request

Example response

Billing & credits

Deposit credits

Request parameters

Response fields

Example request

Example response

Direct deduct

Request parameters

Response fields

Example request

Example response

Freeze credits

Request parameters

Response fields

Example request

Example response

Consume frozen credits

Request parameters

Response fields

Example request

Example response

Unfreeze credits

Request parameters

Response fields

Example request

Example response