# Billing & Plans

> Aerostack billing — platform plans plus a pay-per-use wallet for bot conversations, agent runs, and marketplace tools. Predictable costs, flexible scale.

Aerostack uses a combination of platform plans and a pay-per-use wallet to give you predictable costs with flexible scaling.

---

## How Billing Works

There are two billing mechanisms in Aerostack:

### 1. Platform Plans

Your platform plan (Free, Starter, Pro, Business, or Enterprise) determines your resource limits: how many workspaces you can create, how many API calls you can make per month, how much storage you get, and which features are available.

Plans are billed monthly or yearly. Yearly billing saves 25%.

### 2. Pay-Per-Use Wallet

The prepaid wallet covers variable-cost operations that scale with usage:

- **Bot conversations** -- each message exchange with a bot deducts from your wallet
- **Agent endpoint executions** -- each AI agent run deducts a per-execution fee
- **Marketplace tool calls** -- calling paid community tools deducts the tool creator's price

  **BYOK (Bring Your Own Key)** -- if you provide your own LLM API keys (OpenAI, Anthropic, etc.), bot conversations and agent executions that use those keys incur zero platform cost. You only pay your LLM provider directly.

---

## Plan Overview

| Feature | Free | Starter | Pro | Business | Enterprise |
|---------|------|---------|-----|----------|------------|
| **Price** | $0 | $19/mo | $49/mo | $149/mo | Custom |
| **Yearly price** | $0 | $171/yr | $441/yr | $1,341/yr | Custom |
| **Projects** | 10 | 5 | Unlimited | 50 | Unlimited |
| **MCP Workspaces** | 3 | 10 | 50 | 200 | Unlimited |
| **API Requests/mo** | 50K | 500K | 2M | 10M | Unlimited |
| **AI Tokens/mo** | 100K | 1M | 10M | 100M | Unlimited |
| **Storage** | 2.5 GB | 7 GB | 30 GB | 110 GB | Unlimited |
| **Team Members** | 1 | 3 | 10 | 25 | Unlimited |
| **Gateway APIs** | 3 | 10 | 50 | 200 | Unlimited |

See [Plans](/billing/plans) for the complete feature matrix.

---

## Getting Started

### Check Your Current Plan

```bash
curl https://api.aerostack.dev/api/billing \
  -H "Authorization: Bearer YOUR_JWT"
```

**Response:**

```json
{
  "plan_tier": "free",
  "status": "active",
  "billing_interval": "monthly",
  "current_period_start": null,
  "current_period_end": null
}
```

### View Available Plans

```bash
curl https://api.aerostack.dev/api/billing/plans
```

This returns all plans with their pricing and feature lists.

### Check Your Usage

```bash
curl https://api.aerostack.dev/api/billing/usage \
  -H "Authorization: Bearer YOUR_JWT"
```

**Response:**

```json
{
  "tier": "starter",
  "period": "2026-03",
  "usage": {
    "api_requests": { "used": 42000, "limit": 500000 },
    "ai_tokens": { "used": 150000, "limit": 1000000 },
    "gateway_requests": { "used": 3000, "limit": 50000 },
    "mcp_proxy_calls": { "used": 1200, "limit": 50000 }
  },
  "resource_counts": {
    "projects": { "limit": 5 },
    "team_members": { "limit": 3 },
    "gateway_apis": { "limit": 10 },
    "mcp_workspaces": { "limit": 10 },
    "realtime_connections": { "limit": 1000 }
  }
}
```

---

## Grace Period

When you approach your plan limits, Aerostack provides a **grace buffer** before hard-blocking:

| Plan | Grace % |
|------|---------|
| Free | 10% |
| Starter | 15% |
| Pro | 20% |
| Business | 20% |

For example, on the Free plan with 50,000 API requests/month, the hard limit is 55,000 (50,000 + 10% grace). Between 50,000 and 55,000, you are in the grace zone -- your requests succeed but the dashboard shows a warning. Above 55,000, requests are blocked with a `403` response.

  Grace periods are a safety net, not extra quota. Consistently hitting your grace zone is a signal to upgrade your plan.

---

## Upgrade Your Plan

### Via Dashboard

1. Go to **Settings > Billing** in the Aerostack Dashboard
2. Select a plan and billing interval (monthly or yearly)
3. Complete the checkout
4. Your plan is upgraded immediately upon successful payment

### Via API

```bash
curl -X POST https://api.aerostack.dev/api/billing/checkout \
  -H "Authorization: Bearer YOUR_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "tier": "pro",
    "billing_interval": "yearly",
    "success_url": "https://app.aerostack.dev/settings/billing?success=true",
    "cancel_url": "https://app.aerostack.dev/settings/billing"
  }'
```

**Response:**

```json
{
  "url": "https://checkout.example.com/..."
}
```

Redirect the user to the returned URL to complete payment.

---

## Downgrade or Cancel

Canceling your subscription downgrades you to the Free plan at the end of your current billing period. You keep your current plan features until the period ends.

```bash
curl -X POST https://api.aerostack.dev/api/billing/cancel \
  -H "Authorization: Bearer YOUR_JWT"
```

**Response:**

```json
{
  "success": true,
  "message": "Subscription will be canceled at end of billing period"
}
```

  Cancellation is not immediate. You retain your current plan until the billing period ends. After that, you are automatically moved to the Free plan. Your data is preserved, but resources exceeding Free plan limits become read-only.

---

## Next Steps

- [Plans](/billing/plans) -- detailed plan comparison and feature matrix
- [Wallet](/billing/wallet) -- prepaid wallet for pay-per-use billing