Billing API

STACK accounts combine two billing surfaces: a tier subscription that gates account shape (how many agents, services, team members, and free-skill invocations) and awallet that covers variable-cost items (sealed-execution compute, identity verifications, paid-skill invocations, and tier overage). This page covers the endpoints that expose both surfaces.

Tier allowances reset monthly on your billing period anchor. Wallet balance is non-expiring and non-transferable between operators.

GET /v1/billing/balance

Current wallet balance plus tier context. Returns cents; divide by 100 for USD.

json
{
  "operator_id": "op_acme",
  "balance_cents": 12400,
  "tier": "developer",
  "billing_period_start": "2026-04-01T00:00:00Z",
  "billing_period_end": "2026-05-01T00:00:00Z",
  "usage": {
    "passports": 41223,
    "dropoffs": 402,
    "proxy_calls": 8122,
    "free_skill_invocations": 13
  }
}

GET /v1/billing/transactions

Paginated wallet transaction history. Each entry is a credit (top-up) or debit (invocation, overage, identity verification).

Query parameters

  • limit - integer 1–200 (default: 50)
  • offset - integer ≥ 0 (default: 0)
  • type - filter by transaction type: topup | invocation | overage | identity | refund (optional)
json
{
  "count": 1,
  "transactions": [
    {
      "id": "wtxn_9fA2…",
      "type": "topup",
      "amount_cents": 5000,
      "balance_after_cents": 12400,
      "description": "Stripe checkout",
      "created_at": "2026-04-22T10:14:00Z"
    }
  ]
}

POST /v1/billing/topup

Opens a Stripe Checkout session and returns the redirect URL. On successful payment, the webhook credits the wallet; poll /v1/billing/balance until the new balance appears (typically within a few seconds).

Request

json
{ "amount_cents": 5000 }
  • Minimum: 1000 ($10)
  • Maximum: 1000000 ($10,000) per session

Response

json
{
  "checkout_url": "https://checkout.stripe.com/c/pay/cs_…",
  "session_id": "cs_test_a1…"
}

POST /v1/billing/subscribe

Upgrade or change your subscription tier. Downgrades take effect at the end of the current billing period; upgrades take effect immediately (prorated).

Request

json
{ "tier": "studio" }

Response

json
{ "tier": "studio", "effective_at": "2026-04-23T14:35:00Z" }

POST /v1/billing/cancel-subscription

Cancel the current subscription. The tier stays active until the end of the billing period, then drops to free.

POST /v1/billing/refund/:txnId

Refund a top-up transaction back to the original payment method. Only available on transactions of type topup within the refund window (7 days).

Tier limits

Monthly caps. Requests past the cap fall through to overage pricing (wallet-billed) or throw TIER_LIMIT_EXCEEDED for count-based resources.

text
                         free     developer   studio       enterprise
agents                   5        25          100          ∞
services                 3        25          ∞            ∞
team members             1        5           25           ∞
published skills         3        25          100          ∞
passports / month        50k      500k        5M           ∞
drop-offs / month        500      25k         250k         ∞
proxy calls / month      5k       50k         500k         ∞
free-skill invocations   1k       25k         250k         ∞

Overage pricing (wallet-billed)

  • passport - $0.0001 per issue over the monthly cap
  • drop-off - $0.0001 per create over the cap
  • proxy call - $0.001 per call over the cap
  • free-skill invocation - $0.001 per invocation over the cap

Paid-skill invocations are always wallet-billed at the publisher's list price, regardless of tier. Sealed-execution compute and identity verifications are wallet-billed at the upstream cost plus a 15% markup.

Errors

  • INSUFFICIENT_CREDITS (402) - wallet empty on a debit path; caller should prompt a top-up
  • TIER_LIMIT_EXCEEDED (403) - count-based resource (agents, services, members, published skills) at cap; upgrade required
  • CONFLICT (409) - duplicate subscription change request in flight

Enterprise tier is negotiated and may include custom per-transaction pricing and commission rates. The values above are the default starting point; contact sales for custom arrangements.

stack | docs