Skip to main content

​
Credits, Auto-Recharge, and History

This endpoint group covers prepaid credit operations and billing observability.

​
Endpoints

​
Credits and purchases

  • POST /api/billing/:workspaceId/add-credits
  • GET /api/billing/:workspaceId/credit-packages
  • GET /api/billing/:workspaceId/transactions

​
Usage and history

  • GET /api/billing/:workspaceId/usage
  • GET /api/billing/:workspaceId/usage-history
  • GET /api/billing/:workspaceId/history

​
Auto-recharge

  • GET /api/billing/:workspaceId/auto-recharge
  • PUT /api/billing/:workspaceId/auto-recharge
  • POST /api/billing/:workspaceId/auto-recharge/payment-method

​
Permissions

  • billing:read: read-only endpoints
  • billing:manage: add credits and auto-recharge mutations

​
Add credits payload

POST /api/billing/:workspaceId/add-credits 
{
  "amountDollars": 50,
  "currency": "usd"
}
Validation:
  • Amount must be finite number.
  • Minimum: $5.
  • Maximum single purchase: $10,000.
  • Currency currently supports usd only.
  • Amount is sanitized to cent precision before checkout creation.

​
Usage endpoint

GET /api/billing/:workspaceId/usage returns:
  • resource usage counts (links, rules, domains, campaigns, pixels, apiKeys)
  • click/conversion usage for current cycle
  • plan limits
  • credit balance and cycle usage
  • billing cycle dates and subscription status
The response is snapshot-cached for short TTL to reduce repeated analytics reads.

​
Usage history endpoint

GET /api/billing/:workspaceId/usage-history Query params:
  • start_date (optional)
  • end_date (optional)
Returns day-level credit cost breakdown (clicks, conversions, fraud checks, total).

​
Auto-recharge payloads

PUT /api/billing/:workspaceId/auto-recharge 
{
  "enabled": true,
  "thresholdDollars": 10,
  "amountDollars": 50
}
POST /api/billing/:workspaceId/auto-recharge/payment-method 
{
  "paymentMethodId": "pm_xxx"
}
Enabling auto-recharge requires active subscription and saved payment method.

​
Common errors

  • 400: invalid amount/currency/auto-recharge config/payment method
  • 403: missing permission
  • 404: workspace not found
  • 500: analytics/provider fetch failure