Billing

The Billing API gives you programmatic access to your account's usage data, invoices, payment methods, and subscription management.

Base path: /api/v1/billing

---

Current usage

GET /api/v1/billing/usage

Query parameters: dateFrom, dateTo

curl "https://api.voisnap.ai/api/v1/billing/usage?dateFrom=2025-06-01&dateTo=2025-06-30" \
  -H "Authorization: Bearer vsnp_live_..."

Response:

{
  "period": { "from": "2025-06-01", "to": "2025-06-30" },
  "currency": "USD",
  "totalUsd": 502.18,
  "includedInPlan": 0,
  "overage": 502.18,
  "breakdown": {
    "llmTokens": {
      "inputTokens": 24820400,
      "outputTokens": 7246000,
      "costUsd": 218.94
    },
    "tts": {
      "characters": 19584000,
      "costUsd": 163.21
    },
    "stt": {
      "audioSeconds": 894200,
      "costUsd": 89.42
    },
    "telephony": {
      "inboundMinutes": 1482,
      "outboundMinutes": 842,
      "numbers": 3,
      "costUsd": 30.61
    }
  }
}

---

Subscription

Get current subscription

GET /api/v1/billing/subscription

curl https://api.voisnap.ai/api/v1/billing/subscription \
  -H "Authorization: Bearer vsnp_live_..."

Response:

{
  "id": "sub_01HXABC123DEF",
  "plan": "professional",
  "status": "active",
  "billingInterval": "monthly",
  "currentPeriodStart": "2025-06-01T00:00:00Z",
  "currentPeriodEnd": "2025-06-30T23:59:59Z",
  "nextBillingDate": "2025-07-01T00:00:00Z",
  "currency": "USD",
  "baseAmountUsd": 149.00,
  "includedConversations": 0,
  "rateLimits": {
    "apiRequestsPerMinute": 120,
    "voiceHubConnectionsPerMinute": 10,
    "maxConcurrentCalls": 20
  },
  "features": {
    "whiteLabel": false,
    "agencyMode": false,
    "hipaaCompliance": false,
    "ssoSaml": false,
    "dedicatedSupport": false
  },
  "cancelAtPeriodEnd": false,
  "createdAt": "2025-01-15T10:00:00Z"
}

Upgrade subscription

POST /api/v1/billing/subscription/upgrade

curl -X POST https://api.voisnap.ai/api/v1/billing/subscription/upgrade \
  -H "Authorization: Bearer vsnp_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "plan": "business", "billingInterval": "annual" }'

Response:

{
  "id": "sub_01HXABC123DEF",
  "plan": "business",
  "status": "active",
  "billingInterval": "annual",
  "effectiveDate": "2025-06-16T00:00:00Z",
  "prorationAmountUsd": 84.50,
  "nextBillingDate": "2026-06-01T00:00:00Z"
}

Downgrade subscription

POST /api/v1/billing/subscription/downgrade

Downgrades take effect at the end of the current billing period.

curl -X POST https://api.voisnap.ai/api/v1/billing/subscription/downgrade \
  -H "Authorization: Bearer vsnp_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "plan": "starter" }'

Cancel subscription

POST /api/v1/billing/subscription/cancel

curl -X POST https://api.voisnap.ai/api/v1/billing/subscription/cancel \
  -H "Authorization: Bearer vsnp_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Switching to another provider", "feedback": "Missing feature X" }'

Sets cancelAtPeriodEnd: true. The subscription remains active until currentPeriodEnd.

---

Invoices

List invoices

GET /api/v1/billing/invoices

curl https://api.voisnap.ai/api/v1/billing/invoices \
  -H "Authorization: Bearer vsnp_live_..."

Response:

{
  "data": [
    {
      "id": "inv_01HXMN8ZABC",
      "number": "VSNP-2025-0006",
      "status": "paid",
      "currency": "USD",
      "amountUsd": 651.18,
      "periodStart": "2025-06-01T00:00:00Z",
      "periodEnd": "2025-06-30T23:59:59Z",
      "paidAt": "2025-07-01T00:10:22Z",
      "pdfUrl": "https://billing.voisnap.ai/invoices/inv_01HXMN8ZABC.pdf"
    },
    {
      "id": "inv_01HXMN7ZBC",
      "number": "VSNP-2025-0005",
      "status": "paid",
      "currency": "USD",
      "amountUsd": 602.44,
      "periodStart": "2025-05-01T00:00:00Z",
      "periodEnd": "2025-05-31T23:59:59Z",
      "paidAt": "2025-06-01T00:08:14Z",
      "pdfUrl": "https://billing.voisnap.ai/invoices/inv_01HXMN7ZBC.pdf"
    }
  ],
  "page": 1,
  "pageSize": 20,
  "total": 6,
  "totalPages": 1
}

Get an invoice

GET /api/v1/billing/invoices/{invoiceId}

---

Payment methods

List payment methods

GET /api/v1/billing/payment-methods

Response:

{
  "data": [
    {
      "id": "pm_01HXABC...",
      "type": "card",
      "isDefault": true,
      "card": {
        "brand": "visa",
        "last4": "4242",
        "expMonth": 12,
        "expYear": 2027
      },
      "addedAt": "2025-01-15T10:00:00Z"
    }
  ]
}

Add a payment method

POST /api/v1/billing/payment-methods

Returns a Stripe SetupIntent client secret for use with Stripe.js:

curl -X POST https://api.voisnap.ai/api/v1/billing/payment-methods \
  -H "Authorization: Bearer vsnp_live_..."

Response:

{
  "setupIntentClientSecret": "seti_1ABC...client_secret_xyz"
}

Use stripe.confirmCardSetup(clientSecret) in your frontend to complete setup.

Remove a payment method

DELETE /api/v1/billing/payment-methods/{paymentMethodId}

Set default payment method

POST /api/v1/billing/payment-methods/{paymentMethodId}/set-default

---

Plans reference

Plan	Monthly	Annual	api-standard rate	Concurrent calls
Starter	$49	$39/mo	60/min	5
Professional	$149	$119/mo	120/min	20
Business	$399	$319/mo	300/min	50
Enterprise	Custom	Custom	Custom	Custom

Usage (LLM, TTS, STT, telephony) is billed at cost plus a platform margin on all plans. See current pricing at voisnap.ai/pricing.