> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chowder.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Subscriptions & Billing

> Chowder's subscription tiers, instance limits, and how billing works with Stripe.

# 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

| Tier        | Instance limit | How to get it           |
| ----------- | -------------- | ----------------------- |
| **Shrimp**  | 1              | Free — you start here   |
| **Crab**    | 10             | Self-serve checkout     |
| **Lobster** | 500            | Self-serve checkout     |
| **Whale**   | Unlimited      | Contact us (enterprise) |

<CardGroup cols={2}>
  <Card title="Shrimp (free)" icon="shrimp">
    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.
  </Card>

  <Card title="Crab" icon="compact-disc">
    Ten instances. Good for small teams, multi-agent setups, or production apps with moderate scale.
  </Card>

  <Card title="Lobster" icon="server">
    Five hundred instances. For platforms that run agents on behalf of their users. Serious scale.
  </Card>

  <Card title="Whale" icon="whale">
    Unlimited. Enterprise pricing, custom terms. [Reach out](https://chowder.dev/contact) if you're at this level.
  </Card>
</CardGroup>

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

```json theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
{
  "detail": "Instance limit reached (10/10). Upgrade your subscription."
}
```

<Note>
  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.
</Note>

## Upgrading

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

<Steps>
  <Step title="Create a checkout session">
    ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    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.
  </Step>

  <Step title="Redirect to Stripe">
    Send your user (or yourself) to the returned URL. Stripe handles the payment form, card validation, and receipt.
  </Step>

  <Step title="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.
  </Step>
</Steps>

No manual intervention needed. Once the webhook lands, you can immediately create more instances.

## Checking your subscription

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
curl https://api.chowder.dev/v1/subscription \
  -H "Authorization: Bearer chd_org_abc123..."
```

```json theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
{
  "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?

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
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

<Warning>
  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.
</Warning>

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

<Accordion title="What happens if I hit the limit mid-deploy?">
  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.
</Accordion>

<Accordion title="Can I downgrade from Lobster to Crab?">
  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.
</Accordion>

<Accordion title="Is the Shrimp tier really free?">
  Yes. One instance, full API access, no credit card, no time limit. You can use it forever. If you need more instances, upgrade.
</Accordion>