Skip to main content

​
Subscriptions & Billing

Chowder uses a simple tier-based subscription model. Your tier determines how many instances you can run. Billing is handled entirely through Stripe.

​
Tiers

TierInstance limitHow to get it
Shrimp1Free — you start here
Crab10Self-serve checkout
Lobster500Self-serve checkout
WhaleUnlimitedContact us (enterprise)

Shrimp (free)

One instance, no credit card. Great for trying things out, personal projects, or building a proof of concept. You get the full API — just limited to a single instance.

Crab

Ten instances. Good for small teams, multi-agent setups, or production apps with moderate scale.

Lobster

Five hundred instances. For platforms that run agents on behalf of their users. Serious scale.

Whale

Unlimited. Enterprise pricing, custom terms. Reach out if you’re at this level.

​
How limits work

Instance limits are enforced at creation time. If you’re on the Crab tier (10 instances) and already have 10 running, the next POST /v1/instances will return a 402: 
{
  "detail": "Instance limit reached (10/10). Upgrade your subscription."
}
Only non-terminated instances count toward your limit. If you delete an instance, that slot opens up immediately. Stopped instances still count — they’re hibernated, not gone.

​
Upgrading

The upgrade flow uses Stripe Checkout — a hosted payment page that handles all the payment UI for you.
1

Create a checkout session

curl -X POST https://api.chowder.dev/v1/subscription/checkout \
  -H "Authorization: Bearer chd_org_abc123..." \
  -H "Content-Type: application/json" \
  -d '{"tier": "crab"}'
This returns a Stripe Checkout URL.
2

Redirect to Stripe

Send your user (or yourself) to the returned URL. Stripe handles the payment form, card validation, and receipt.
3

Webhook updates your tier

When payment completes, Stripe fires a checkout.session.completed webhook. Chowder processes it and upgrades your organization’s tier and instance limit automatically.
No manual intervention needed. Once the webhook lands, you can immediately create more instances.

​
Checking your subscription

curl https://api.chowder.dev/v1/subscription \
  -H "Authorization: Bearer chd_org_abc123..."

{
  "tier": "crab",
  "instance_limit": 10,
  "instance_count": 3,
  "stripe_customer_id": "cus_...",
  "stripe_subscription_id": "sub_..."
}

​
Managing your subscription

Already on a paid tier and need to change plans, update payment info, or cancel? 
curl -X POST https://api.chowder.dev/v1/subscription/portal \
  -H "Authorization: Bearer chd_org_abc123..."
This returns a Stripe Billing Portal URL where you can:
  • Switch between Crab and Lobster
  • Update your payment method
  • View invoices
  • Cancel your subscription
If you cancel your subscription, your organization downgrades to the Shrimp tier (1 instance). Existing instances beyond the limit won’t be deleted, but you won’t be able to create new ones until you’re back within the limit.

​
Per-instance billing

On paid tiers, Chowder tracks instance count as a line item on your Stripe subscription. When you create an instance, the count goes up. When you delete one, it goes down. This happens automatically — Chowder syncs the quantity with Stripe after every create and delete. This means your bill reflects what you’re actually using, not what your tier allows. Being on the Crab tier doesn’t mean you’re paying for 10 instances — you’re paying for however many you have running.
The instance creation call will fail with a 402 before any sandbox is provisioned. No partial resources, no zombie instances. You’ll need to either delete an existing instance or upgrade.
Yes, through the Stripe billing portal. If you have more instances than the new tier allows, you won’t be able to create new ones until you’re within the limit, but existing instances keep running.
Yes. One instance, full API access, no credit card, no time limit. You can use it forever. If you need more instances, upgrade.