---
title: Billing
description: Per-settled-transaction pricing, plans, usage tracking, and Stripe-powered billing for CodeSpar.
---

import { Callout } from "fumadocs-ui/components/callout";

# 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

| | Open Source | Orchestration | Enterprise |
|---|---|---|---|
| **Price** | Free | $0.10 / tx + 0.5% cross-border FX | Custom |
| **How you pay** | Self-host, no sign-up | Per settled transaction, no minimum | Volume-based, bespoke terms |
| **MCP servers + SDK** | All, MIT | All, hosted | All, region-pinned option |
| **Policy engine + HMAC mandates** | Bring your own | Included | Included + custom rules |
| **Payment router** | — | Included | Included |
| **Audit ledger** | — | Included, hash-chained | Enhanced + signed exports |
| **Escrow + milestones** | — | Included | Included |
| **Uptime target** | Best-effort (self-hosted) | 99.95% | 99.99% + SLA |
| **SSO · SAML** | — | — | Included |
| **Support** | GitHub issues · community | Email · 24h response | 24/7 + Slack · named support |

<Callout type="info">
All tiers access the same MCP servers and the same 14 meta-tools. The differentiation is the managed orchestration layer (policies, mandates, routing, escrow, audit), uptime guarantees, and enterprise procurement features. There are no feature gates on the catalog.
</Callout>

## 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.

| Counts | Does NOT count |
|---|---|
| Successful charge (Pix, boleto, card, SPEI, wallet) | Abandoned checkout |
| Payout to bank account | Never-confirmed hold |
| Refund | Cancelled before capture |
| Transfer between accounts | Session creation, `session.tools()`, `session.connections()` |
| Terminal failure after retries | Tool discovery calls, `codespar_discover` |
| | NF-e / CFDI issuance (included in the transaction price) |
| | Shipping labels + tracking (included) |
| | WhatsApp / SMS / email (included) |
| | ERP sync, webhook delivery (included) |

<Callout type="info">
Supporting operations — invoicing, shipping, messaging, ERP — are priced **inside** the transaction. Issuing an NF-e for a R$150 Pix charge is a single $0.10 transaction, not one charge + one invoice.
</Callout>

### 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

| Business | Monthly volume | Settled tx | Cross-border | Estimated cost |
|----------|---------------|-----------|--------------|----------------|
| Small SaaS | R$50k | 500 | 0% | ~R$250 / mo |
| Marketplace | R$500k | 5,000 | 25% | ~R$3,125 / mo |
| Cross-border fintech | R$5M | 20,000 | 80% | ~R$30,000 / mo |

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

## Tracking usage

### Via the dashboard

Visit [codespar.dev/dashboard/billing](https://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

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

**Response:**

```json
{
  "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

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

**Response:**

```json
{
  "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:

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

Use the [Observability dashboard](/docs/debugging) 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:

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

**Response:**

```json
{
  "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](mailto:sales@codespar.dev) with bespoke terms.

### Managing your subscription

```bash
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

<NextStepsGrid items={[
  { label: "CONCEPT", title: "Sessions", description: "Session lifecycle, scoping, and userId-based attribution.", href: "/docs/concepts/sessions" },
  { label: "CONCEPT", title: "Tools & Meta-Tools", description: "What each meta-tool does — tool calls are not billing events.", href: "/docs/concepts/tools" },
  { label: "DEBUGGING", title: "Debugging", description: "Tool-call logs and observability — free to inspect.", href: "/docs/debugging" },
  { label: "PRICING", title: "Public Pricing Page", description: "Scenarios, comparison matrix, and FAQ.", href: "https://codespar.dev/pricing" },
  { label: "COOKBOOK", title: "Cross-Border Fintech", description: "Explicit 0.5% FX surcharge math on USD → BRL.", href: "/docs/cookbooks/cross-border-fintech" },
  { label: "COOKBOOK", title: "Marketplace Payout", description: "Two settled transactions per order (charge + payout).", href: "/docs/cookbooks/marketplace-payout" },
  { label: "COOKBOOK", title: "Multi-Tenant Agent", description: "metadata.tenant_id for per-tenant usage aggregation.", href: "/docs/cookbooks/multi-tenant" },
]} />