Billing tools

The universal billing.* namespace — credit balance, usage, transaction history, and cost reference. Every workspace has these regardless of which product services it uses, since credits are the platform-wide unit.

All endpoints follow the pattern POST https://mcp.vlozi.app/tools/billing.<name> with Authorization: Bearer ls_xxx. All responses use this envelope:

{ "data": <payload>, "error": null }   // success
{ "data": null,      "error": "..." }  // failure (with HTTP 4xx/5xx)

`billing.get_balance`

Current credit balance, split into buckets. Check this before any paid action to confirm headroom.

Scope: billing:coins.read

Input: none

Response: { balance: number, buckets: { subscription: number, subscriptionExpiresAt: string | null, permanent: number } }

NOTE

The subscription bucket expires at the end of the billing period; the permanent bucket (top-ups) never expires. balance is the sum of both.

curl -X POST https://mcp.vlozi.app/tools/billing.get_balance \
  -H "Authorization: Bearer $VLOZI_API_KEY"

`billing.get_usage`

Where credits went — total spend plus a per-service breakdown over a trailing window.

Scope: billing:coins.read

Input: { days?: number } (7, 30, or 90 — default 30)

Response: { days: number, total: number, byService: { service: string, spent: number }[] }

curl -X POST https://mcp.vlozi.app/tools/billing.get_usage \
  -H "Authorization: Bearer $VLOZI_API_KEY" \
  -d '{"days": 7}'

`billing.list_transactions`

Recent credit ledger entries, newest first — hold/capture pairs are already consolidated to net spend.

Scope: billing:coins.read

Input: { page?: number } (0-based, default 0, 20 per page)

Response: { transactions: { amount, balanceAfter, reason, description, referenceId, createdAt }[] }

curl -X POST https://mcp.vlozi.app/tools/billing.list_transactions \
  -H "Authorization: Bearer $VLOZI_API_KEY" \
  -d '{"page": 0}'

`billing.get_summary`

Billing overview: current plan, credit balance and buckets, subscription status, and any active alerts (trial ending, past due, low balance).

Scope: billing:plans.read

Input: none

Response: { plan: string, creditBalance: number, creditBuckets: object, subscriptionStatus: string | null, alerts: object[] }

curl -X POST https://mcp.vlozi.app/tools/billing.get_summary \
  -H "Authorization: Bearer $VLOZI_API_KEY"

`billing.get_costs`

The credit price catalogue — how many credits every paid action costs across every service. Use to explain or estimate costs to a user before they act.

Scope: billing:plans.read

Input: none

Response: { costs: Record<string, number> } — a flat map of cost keys (e.g. BLOG_AI_GENERATE) to their credit price.

curl -X POST https://mcp.vlozi.app/tools/billing.get_costs \
  -H "Authorization: Bearer $VLOZI_API_KEY"