Billing API

Full billing dashboard backend for the LVNG platform. Query credit balances and burn rates, view aggregated usage charts, configure auto-reload, manage payment methods, download invoices, and set up spending alerts. All endpoints require JWT authentication.

Base path: /api/v2/billing

Balance & Usage

Query current credit balance, burn rate, and aggregated usage data for charts.

GET/api/v2/billing/balanceAuthenticated

Get current credit balance, included and purchased credits, and the burn rate (average credits per hour over the last 24 hours).

Request

cURL

curl -X GET "https://api.lvng.ai/api/v2/billing/balance" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response 200

{
  "success": true,
  "data": {
    "balance": 4250.00,
    "included_credits": 5000,
    "purchased_credits": 2000,
    "burn_rate_per_hour": 12.50,
    "updated_at": "2026-04-01T12:00:00.000Z"
  }
}

GET/api/v2/billing/usage-chartAuthenticated

Get aggregated usage data for dashboard charts, broken down by day and model.

Query Parameters

startstringrequired

Start date in ISO 8601 format.

endstringrequired

End date in ISO 8601 format.

granularitystring

Aggregation granularity: "day" (default) or "week".

Request

cURL

curl -X GET "https://api.lvng.ai/api/v2/billing/usage-chart" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response 200

{
  "success": true,
  "data": {
    "daily_usage": [
      { "date": "2026-03-01", "credits": 45.20, "requests": 120 },
      { "date": "2026-03-02", "credits": 38.10, "requests": 95 }
    ],
    "model_breakdown": [
      { "model": "claude-sonnet", "credits": 520, "requests": 1800 },
      { "model": "claude-haiku", "credits": 85, "requests": 3200 }
    ]
  }
}

Auto-Reload

Configure automatic credit top-up when your balance drops below a threshold.

GET/api/v2/billing/auto-reloadAuthenticated

Get current auto-reload configuration.

Request

cURL

curl -X GET "https://api.lvng.ai/api/v2/billing/auto-reload" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response 200

{
  "success": true,
  "data": {
    "enabled": true,
    "threshold_credits": 500,
    "reload_amount": 5000,
    "payment_method_id": "pm_abc123",
    "updated_at": "2026-03-15T10:00:00.000Z"
  }
}

POST/api/v2/billing/auto-reloadAuthenticated

Create or update auto-reload configuration. Upserts on user_id.

Body Parameters

enabledboolean

Whether auto-reload is active. Defaults to false.

threshold_creditsnumber

Credit balance threshold that triggers a reload. Must be non-negative. Defaults to 500.

reload_amountnumber

Number of credits to add on reload. Must be positive. Defaults to 5000.

payment_method_idstring

UUID of the payment method to charge.

Request

cURL

curl -X POST "https://api.lvng.ai/api/v2/billing/auto-reload" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Response 200

{
  "success": true,
  "data": {
    "user_id": "a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11",
    "enabled": true,
    "threshold_credits": 1000,
    "reload_amount": 10000,
    "payment_method_id": "pm_abc123",
    "updated_at": "2026-04-01T12:00:00.000Z"
  }
}

Spending Alerts

Create alerts to be notified when spending exceeds a threshold over a given period. Optionally set a hard cap to block usage.

POST/api/v2/billing/alertsAuthenticated

Create a spending alert for a given period.

Body Parameters

periodstringrequired

Alert period: "daily", "weekly", or "monthly".

threshold_creditsnumberrequired

Credit threshold that triggers the alert. Must be positive.

hard_capboolean

If true, blocks usage when threshold is reached. Defaults to false.

workspace_idstring

Scope alert to a specific workspace.

Request

cURL

curl -X POST "https://api.lvng.ai/api/v2/billing/alerts" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Response 201

{
  "success": true,
  "data": {
    "id": "alert_abc123",
    "user_id": "a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11",
    "period": "daily",
    "threshold_credits": 500,
    "hard_cap": false,
    "workspace_id": null,
    "created_at": "2026-04-01T12:00:00.000Z"
  }
}

GET/api/v2/billing/alertsAuthenticated

List all spending alerts for the authenticated user.

Request

cURL

curl -X GET "https://api.lvng.ai/api/v2/billing/alerts" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response 200

{
  "success": true,
  "data": [
    {
      "id": "alert_abc123",
      "period": "daily",
      "threshold_credits": 500,
      "hard_cap": false,
      "workspace_id": null,
      "created_at": "2026-04-01T12:00:00.000Z"
    }
  ]
}

DELETE/api/v2/billing/alerts/:idAuthenticated

Delete a spending alert.

Path Parameters

idstringrequired

UUID of the alert to delete.

Request

cURL

curl -X DELETE "https://api.lvng.ai/api/v2/billing/alerts/{id}" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response 200

{
  "success": true,
  "message": "Alert deleted"
}

Invoices

List and download billing invoices.

GET/api/v2/billing/invoicesAuthenticated

List all invoices for the authenticated user, ordered by period end date (newest first).

Request

cURL

curl -X GET "https://api.lvng.ai/api/v2/billing/invoices" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response 200

{
  "success": true,
  "data": [
    {
      "id": "inv_abc123",
      "period_start": "2026-03-01",
      "period_end": "2026-03-31",
      "subscription_amount": 49.00,
      "credits_included": 5000,
      "credits_used": 6200,
      "overage_credits": 1200,
      "overage_amount": 12.00,
      "total_amount": 61.00,
      "status": "paid",
      "created_at": "2026-04-01T00:00:00.000Z"
    }
  ]
}

GET/api/v2/billing/invoices/:id/downloadAuthenticated

Download invoice data as a JSON file. Returns with Content-Disposition header for file download.

Path Parameters

idstringrequired

UUID of the invoice.

Request

cURL

curl -X GET "https://api.lvng.ai/api/v2/billing/invoices/{id}/download" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response 200

{
  "invoice_id": "inv_abc123",
  "period_start": "2026-03-01",
  "period_end": "2026-03-31",
  "subscription_amount": 49.00,
  "credits_included": 5000,
  "credits_used": 6200,
  "overage_credits": 1200,
  "overage_amount": 12.00,
  "total_amount": 61.00,
  "status": "paid",
  "created_at": "2026-04-01T00:00:00.000Z"
}

Payment Methods

Manage payment methods on file. Stripe integration ready.

POST/api/v2/billing/payment-methodsAuthenticated

Add a payment method. Currently supports card type with brand, last four digits, and expiration.

Body Parameters

brandstringrequired

Card brand (e.g. "visa", "mastercard").

last_fourstringrequired

Last 4 digits of the card number.

exp_monthnumberrequired

Expiration month (1-12).

exp_yearnumberrequired

Expiration year (must not be in the past).

is_defaultboolean

Set as default payment method. Defaults to false.

Request

cURL

curl -X POST "https://api.lvng.ai/api/v2/billing/payment-methods" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Response 201

{
  "success": true,
  "data": {
    "id": "pm_abc123",
    "type": "card",
    "brand": "visa",
    "last_four": "4242",
    "exp_month": 12,
    "exp_year": 2028,
    "is_default": true,
    "created_at": "2026-04-01T12:00:00.000Z"
  }
}

GET/api/v2/billing/payment-methodsAuthenticated

List all payment methods for the authenticated user.

Request

cURL

curl -X GET "https://api.lvng.ai/api/v2/billing/payment-methods" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response 200

{
  "success": true,
  "data": [
    {
      "id": "pm_abc123",
      "type": "card",
      "brand": "visa",
      "last_four": "4242",
      "exp_month": 12,
      "exp_year": 2028,
      "is_default": true,
      "created_at": "2026-04-01T12:00:00.000Z"
    }
  ]
}

DELETE/api/v2/billing/payment-methods/:idAuthenticated

Remove a payment method. Verifies ownership before deletion.

Path Parameters

idstringrequired

UUID of the payment method.

Request

cURL

curl -X DELETE "https://api.lvng.ai/api/v2/billing/payment-methods/{id}" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response 200

{
  "success": true,
  "message": "Payment method deleted"
}

Swarm Compute

Get swarm compute billing totals for a workspace.

GET/api/v2/billing/swarm-computeAuthenticated

Get swarm compute billing totals for a workspace over a date range. Defaults to the current calendar month.

Query Parameters

workspace_idstringrequired

UUID of the workspace.

startstring

Start date (ISO 8601). Defaults to first of current month.

endstring

End date (ISO 8601). Defaults to now.

Request

cURL

curl -X GET "https://api.lvng.ai/api/v2/billing/swarm-compute" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response 200

{
  "success": true,
  "total_compute_credits": 1250,
  "total_tasks": 48,
  "by_agent": [
    { "agent_id": "agt_001", "agent_name": "Research Agent", "credits": 800, "tasks": 30 },
    { "agent_id": "agt_002", "agent_name": "Data Processor", "credits": 450, "tasks": 18 }
  ]
}