Billing & Quotas

CodeSpar bills based on tool calls. Each time your agent executes a tool through a session -- whether via session.execute(), session.send(), or session.sendStream() -- it counts as one call. There are no charges for creating sessions, listing tools, browsing the server catalog, or managing API keys.

This model is deliberately simple. You pay for the commerce operations your agents perform, not for infrastructure or seat counts.

Plans

What counts as a tool call?

A tool call is counted each time your agent invokes a tool through a session. The distinction is straightforward:

Billing example

A typical e-commerce agent conversation might look like this:

At 6 calls per order, the Hobby plan (20,000 calls) supports approximately 3,300 orders per month.

Quota enforcement

CodeSpar enforces quotas at two thresholds:

Soft limit (90%)

When you reach 90% of your monthly quota, a warning header is added to all API responses:

X-CodeSpar-Quota-Warning: You have used 18,000 of 20,000 tool calls this period.

This header is informational. All operations continue to work normally.

Hard limit (100%)

When you reach 100% of your quota, tool executions return an HTTP 429 error:

curl -X POST https://api.codespar.dev/v1/sessions/ses_abc123/execute \
  -H "Authorization: Bearer csk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"name": "codespar_pay", "arguments": {"method": "pix", "amount": 9990, "currency": "BRL"}}'

Response -- 429 Too Many Requests:

{
  "error": "quota_exceeded",
  "message": "Monthly tool call quota exceeded. Upgrade your plan or wait for the next billing cycle.",
  "quota": 20000,
  "used": 20000,
  "resets_at": "2026-05-01T00:00:00Z",
  "upgrade_url": "https://codespar.dev/dashboard/billing"
}

Handling quota errors in code

try {
  const result = await session.execute({
    name: "codespar_pay",
    arguments: { method: "pix", amount: 9990, currency: "BRL" },
  });
} catch (error) {
  if (error.code === "quota_exceeded") {
    console.error(`Quota exceeded. Resets at: ${error.resets_at}`);
    console.error(`Upgrade at: ${error.upgrade_url}`);
    // Inform the user or trigger an upgrade flow
  }
}

Tracking usage

Via the dashboard

Visit codespar.dev/dashboard/billing to see:

• Current month's tool call usage vs. quota (with progress bar and percentage)
• Usage breakdown by meta-tool and server-specific tool
• Daily usage chart for the current billing period
• Historical usage across previous months
• Billing history with downloadable invoices

Via the Usage API

curl https://api.codespar.dev/v1/usage \
  -H "Authorization: Bearer csk_live_..."

Response:

{
  "period": {
    "start": "2026-04-01T00:00:00Z",
    "end": "2026-04-30T23:59:59Z"
  },
  "quota": 200000,
  "used": 47832,
  "remaining": 152168,
  "percentage": 23.9,
  "breakdown": {
    "codespar_discover": 1240,
    "codespar_checkout": 8901,
    "codespar_pay": 15432,
    "codespar_invoice": 12300,
    "codespar_ship": 6789,
    "codespar_notify": 3170
  }
}

Via the Billing API

curl https://api.codespar.dev/v1/billing \
  -H "Authorization: Bearer csk_live_..."

Response:

{
  "plan": "starter",
  "status": "active",
  "price_cents": 2900,
  "currency": "USD",
  "current_period": {
    "start": "2026-04-01T00:00:00Z",
    "end": "2026-04-30T23:59:59Z"
  },
  "quota": 200000,
  "used": 47832,
  "overage_enabled": false,
  "payment_method": {
    "type": "card",
    "last4": "4242",
    "brand": "visa",
    "exp_month": 12,
    "exp_year": 2027
  },
  "stripe_customer_id": "cus_abc123",
  "portal_url": "https://billing.stripe.com/p/session/abc123"
}

Stripe integration

Billing is powered by Stripe. All payment processing, invoice generation, and subscription management happens through Stripe's infrastructure.

Upgrading your plan

Upgrades take effect immediately. Your new quota applies right away, and the price difference is prorated for the remaining days in the billing cycle.

Via the dashboard:

Dashboard > Billing > Upgrade Plan > Select new plan > Confirm

Programmatic upgrade (redirect to Stripe Checkout):

curl -X POST https://api.codespar.dev/v1/billing/checkout \
  -H "Authorization: Bearer csk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"plan": "growth"}'

Response:

{
  "checkout_url": "https://checkout.stripe.com/c/pay_abc123...",
  "expires_at": "2026-04-15T11:30:00Z"
}

Redirect the user to checkout_url to complete the upgrade via Stripe Checkout.

Managing your subscription

Use the Stripe Customer Portal to update payment methods, download invoices, or cancel your subscription:

curl -X POST https://api.codespar.dev/v1/billing/portal \
  -H "Authorization: Bearer csk_live_..."

Response:

{
  "portal_url": "https://billing.stripe.com/p/session/abc123..."
}

The portal URL is a one-time link valid for 24 hours.

Downgrading

Downgrades take effect at the end of the current billing cycle. You retain your current quota until the period ends, then the new plan's limits apply.

Overage billing (Growth plan only)

Growth plan customers can enable overage billing instead of hard quota enforcement. When enabled:

• Tool calls beyond the 2M monthly quota are billed at $0.20 per 1,000 calls
• Overage charges appear on the next invoice as a separate line item
• There is no cap on overage -- your agents continue operating without interruption
• Enable or disable overage in Dashboard > Billing > Overage Settings

Cost optimization

1. Cache codespar_discover results. Call it once per conversation, not per turn. The response is stable within a session.
2. Use session.send() for notifications. Fire-and-forget costs the same as execute but frees your agent to continue immediately.
3. Scope sessions narrowly. Fewer servers means fewer discovery calls and a smaller tool list for the LLM (lower token costs on your AI provider bill too).
4. Use presets. They bundle only the servers needed for a workflow, avoiding unnecessary connections.
5. Monitor usage weekly. Set up alerts in the dashboard to catch unexpected spikes before they drain your quota.
6. Reuse sessions across conversation turns. Creating a new session per message wastes resources and adds latency.

Next steps

• Authentication -- API key management and security
• Sessions -- How sessions relate to billing
• FAQ -- Common billing and pricing questions