Billing

CodeSpar bills for settled transactions — money movements that reach a terminal state through the CodeSpar runtime. Tool calls, session creation, tool listing, catalog browsing, and every supporting operation (invoicing, shipping labels, WhatsApp notifications, ERP syncs) are included in the transaction price. You are not charged per API call. You are charged per settled money movement.

This model is deliberately simple. You pay when value moves.

Plans

What counts as a settled transaction?

A settled transaction is a single movement of money through CodeSpar that reaches a terminal state — succeeded, refunded, or permanently failed after retries exhaust. Transactions that never settle (abandoned checkouts, never-confirmed holds, cancelled before capture) are free.

Cross-border surcharge

When a transaction involves currency conversion (e.g., a USD card charge settled to a BRL account, or a USDC payout), an additional 0.5% of the converted amount is billed on top of the base $0.10. The surcharge only applies to the cross-border leg — domestic transactions stay at the flat $0.10.

Example scenarios

Each row shows the fully-loaded cost including FX surcharges where applicable.

Tracking usage

Via the dashboard

Visit codespar.dev/dashboard/billing to see:

• Current month's settled transactions (count + volume)
• Breakdown by provider, currency, domestic vs cross-border
• Daily settlement chart for the current billing period
• Invoice history with downloadable PDFs
• Stripe Customer Portal for payment method management

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"
  },
  "settled_transactions": 1847,
  "cross_border_transactions": 312,
  "cross_border_volume_usd": 84200,
  "estimated_cost_usd": 606.70,
  "breakdown_by_provider": {
    "stripe": 892,
    "mercadopago": 651,
    "asaas": 204,
    "other": 100
  },
  "breakdown_by_currency": {
    "BRL": 1458,
    "USD": 289,
    "MXN": 100
  }
}

Via the Billing API

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

Response:

{
  "plan": "orchestration",
  "status": "active",
  "unit_price_usd": 0.10,
  "cross_border_surcharge_pct": 0.5,
  "current_period": {
    "start": "2026-04-01T00:00:00Z",
    "end": "2026-04-30T23:59:59Z"
  },
  "settled_transactions": 1847,
  "estimated_cost_usd": 606.70,
  "stripe_customer_id": "cus_abc123",
  "portal_url": "https://billing.stripe.com/p/session/abc123"
}

Tool-call observability ≠ billing

Every tool call — session.execute(), session.send(), session.sendStream(), every underlying server call — is logged for audit, debugging, and rate-limit enforcement. These logs are not billing events. You can inspect them freely:

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

Use the Observability dashboard to drill into failed calls, provider latency, and retry behavior without worrying about cost per inspection.

Stripe integration

Billing is powered by Stripe. Payment methods, invoice generation, and subscription management run through Stripe Customer Portal.

Upgrading to Orchestration or Enterprise

From self-hosted Open Source to managed Orchestration:

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

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 setup via Stripe Checkout. Enterprise upgrades go through sales@codespar.dev with bespoke terms.

Managing your subscription

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

Returns a Stripe Customer Portal URL for managing payment methods, downloading invoices, or cancelling.

FAQs

Do tool calls count toward billing? No. Only settled transactions are billed. Tool calls are logged for observability and rate-limit enforcement.

What if a transaction fails? Failed transactions (non-terminal) are not charged. Only terminal states — succeeded, refunded, or permanently failed after retry exhaustion — settle and bill.

Is Open Source really unlimited? Yes. MCP servers and the SDK are MIT-licensed on npm. Self-host, no caps, no sign-up. You only need CodeSpar when you want the managed orchestration layer.

What about invoicing, shipping, WhatsApp? All included in the transaction price. Issuing an NF-e for a Pix charge = one $0.10 tx, not one charge + one invoice.

When does the cross-border surcharge apply? Only on the leg that crosses currencies. A domestic BRL Pix charge settled to a BRL account has no surcharge. A USD card charge settled to a BRL account has a 0.5% surcharge on the converted amount.

Next steps