Billing & Plans

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 via Stripe. 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

The wallet is funded via Stripe deposits. You can set up auto-reload to maintain a minimum balance.

Plan Overview

See Plans for the complete feature matrix.

Getting Started

Check Your Current Plan

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

Response:

{
  "plan_tier": "free",
  "status": "active",
  "billing_interval": "monthly",
  "stripe_customer_id": null,
  "stripe_subscription_id": null,
  "current_period_start": null,
  "current_period_end": null
}

View Available Plans

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

This returns all plans with their pricing and feature lists.

Check Your Usage

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

Response:

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

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.

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 Stripe checkout
4. Your plan is upgraded immediately upon successful payment

Via API

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:

{
  "url": "https://checkout.stripe.com/c/pay/cs_live_..."
}

Redirect the user to the returned URL to complete the Stripe checkout.

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.

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

Response:

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

Stripe Customer Portal

Access your Stripe-managed billing portal to update payment methods, view invoices, and manage your subscription:

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

Response:

{
  "url": "https://billing.stripe.com/p/session/..."
}

Next Steps

• Plans — detailed plan comparison and feature matrix
• Wallet — prepaid wallet for pay-per-use billing
• Stripe Integration — webhook setup and Stripe Connect for creators