Skip to content

Billing

OpenClaw Hosted billing combines Stripe subscriptions (base tier fee) with metered usage (compute, tokens, storage). All billing RPCs require API key authentication.

Overview

1
2
3
4
5
6
7
Your deployments
      │ emit usage events (compute, tokens, storage)
      ▼
Control plane aggregates → Stripe metered line items
      │
      ▼
Monthly invoice (base + usage)
  • Base price — per-tier subscription (Starter through Business)
  • Metered dimensions — compute, token_input, token_output, storage
  • Rate card — per-tier unit prices stored in the database (GetRateCard)

BYOK inference mode does not incur ClusterClaw token charges — you pay your provider directly.

Tiers and checkout

Tier Stripe checkout Base subscription
free Not available Dashboard-only tier
starter Yes Lowest deployment limit
hobbyist Yes Discounted usage vs starter
developer Yes 3 deployments (product)
team Yes 5 deployments
business Yes 25 deployments
enterprise Contact sales Custom

Start checkout:

1
2
3
4
5
6
7
8
curl -sS -X POST 'https://api.clusterclaw.ai/openclaw.v1.BillingService/CreateCheckoutSession' \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $CLUSTERCLAW_API_KEY" \
  -d '{
    "tier": "developer",
    "successUrl": "https://www.clusterclaw.ai/dashboard?checkout=success",
    "cancelUrl": "https://clusterclaw.ai/pricing"
  }'

Open the returned url in a browser to complete Stripe Checkout. Defaults apply if URLs are omitted.

Manage payment methods, invoices, and cancellation via Customer Portal:

1
2
3
4
curl -sS -X POST 'https://api.clusterclaw.ai/openclaw.v1.BillingService/CreateBillingPortalSession' \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $CLUSTERCLAW_API_KEY" \
  -d '{"returnUrl": "https://www.clusterclaw.ai/dashboard/settings"}'

Stripe webhooks update stripe_customer_id, stripe_subscription_id, tier, and plan on your customer record.

Subscription status

GetSubscription returns:

Field Meaning
tier Current tier
plan Plan label
status free (no Stripe sub), or Stripe status (active, past_due, …)
cancel_at_period_end Scheduled cancellation
current_period_end Period end (when synced from Stripe) 
1
claw usage    # CLI shorthand for current-period charges

Usage and charges

Event types

Event type Unit Source
compute_small / compute_medium / compute_large hour Running deployment compute
token_input token Platform-managed inference (input)
token_output token Platform-managed inference (output)
storage gb_hour Persistent volume sampling

Exact unit prices depend on tier. Fetch live rates:

1
2
3
4
curl -sS -X POST 'https://api.clusterclaw.ai/openclaw.v1.BillingService/GetRateCard' \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $CLUSTERCLAW_API_KEY" \
  -d '{"tier": "developer"}'

Marketing-friendly rate tables on the pricing page display per-1K-token equivalents; the API stores per-token prices.

Query usage

RPC Purpose
GetCurrentCharges Estimated cost for the current calendar month
GetUsageSummary Aggregated line items for a custom period_start / period_end
GetDeploymentUsage Per-deployment breakdown (via MeteringService)

Example — current month estimate:

1
2
3
4
curl -sS -X POST 'https://api.clusterclaw.ai/openclaw.v1.BillingService/GetCurrentCharges' \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $CLUSTERCLAW_API_KEY" \
  -d '{}'

Response:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
{
  "lineItems": [
    {
      "eventType": "token_input",
      "quantity": "125000",
      "unit": "token",
      "unitPrice": 0.000006,
      "totalCost": 0.75
    }
  ],
  "estimatedTotal": 12.45,
  "periodStart": "...",
  "periodEnd": "..."
}

Usage limits (spending caps)

Configure optional caps on token consumption:

RPC Action
GetUsageLimits List limits
SetUsageLimit Create or update
DeleteUsageLimit Remove a limit

Limit types: token_total, token_input, token_output.

Each limit supports hourly_limit, daily_limit, monthly_limit (0 = unset), and enabled.

1
2
3
4
5
6
7
8
curl -sS -X POST 'https://api.clusterclaw.ai/openclaw.v1.BillingService/SetUsageLimit' \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $CLUSTERCLAW_API_KEY" \
  -d '{
    "limitType": "token_total",
    "monthlyLimit": "5000000",
    "enabled": true
  }'

Limits are enforced by the platform when usage is aggregated — configure them before heavy workloads.

What Stripe bills

Each checkout session includes:

  1. One base price line item for the tier (STRIPE_*_BASE_PRICE_ID)
  2. Metered line items for compute, token input/output, and storage

Legacy fixed-price subscriptions may still exist for grandfathered accounts; the API resolves tier from price IDs on webhook events.

Free tier

Google OAuth signups land on tier: free:

  • Rate card entries exist with zero unit price
  • CreateDeployment is blocked (permission_denied)
  • Upgrade via Stripe checkout to a paid tier

Enterprise

Custom deployment counts, GKE Autopilot (target_class: autopilot), negotiated rates, and SLA are available on the enterprise tier. Use the pricing page contact flow — not self-serve checkout.

Tax and invoices

Stripe hosts invoices and tax settings in the Customer Portal. ClusterClaw does not expose a separate invoice RPC — use portal URLs from CreateBillingPortalSession.