# Billing API

Upgrade your plan via Stripe checkout.

## POST /v1/billing/upgrade

**POST** `/v1/billing/upgrade`

Generate a Stripe checkout URL to upgrade from the free plan. Requires full-access key. Pass a `plan` and optional `period` in the request body to select a tier and billing cadence. If an open checkout session for the same plan+period already exists, it is returned instead of creating a new one.

```request body (optional)
{
  "plan": "developer",  // "developer", "growth", or "scale"
  "period": "annual"    // "monthly" (default) or "annual" (~25% off)
}
// Omit body to default to { plan: "developer", period: "monthly" }.
```

```response — 201 Created (new session)
{
  "checkout_url": "https://checkout.stripe.com/c/pay_...",
  "expires_at": 1741651200,
  "message": "Share this URL with the account owner to complete payment. A link has also been emailed to the account owner."
}
```

```response — 200 OK (existing session)
{
  "checkout_url": "https://checkout.stripe.com/c/pay_...",
  "expires_at": 1741651200,
  "message": "An upgrade checkout session is already active. Share this URL with the account owner to complete payment."
}
```

After payment, your account is upgraded automatically. A confirmation email with the checkout link is sent to the account owner when a new session is created.

### Changing plans

This endpoint is for upgrading from the free plan only. If you are already on a paid plan, manage your subscription through the **Stripe Customer Portal** (accessible from the dashboard billing page). Plan changes — upgrades and downgrades — take effect immediately, and Stripe prorates charges automatically.

### Errors

- `400` — Invalid plan or period
- `409` — Already on a paid plan (use Stripe Customer Portal to change plan or period)
- `503` — Billing not configured on this instance


---

Previous: [Attachments](https://robotomail.com/docs/api/attachments.md) | Next: [Suppressions](https://robotomail.com/docs/api/suppressions.md)