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

# Upgrading

> Upgrade your PingBack plan to unlock more agents, channels, and AI features.

Upgrading your PingBack plan takes two steps: fetch a checkout URL from the API, then complete payment in the Polar.sh checkout flow. Your plan upgrades automatically once payment is confirmed.

## Get a checkout URL

Call `GET /api/v1/billing/checkout-url` with the `plan` query parameter set to `mini` or `pro`. The response returns a `url` you redirect the user to.

**Endpoint:** `GET https://api.pingback.live/api/v1/billing/checkout-url`

**Query parameters:**

| Parameter | Required | Values          |
| --------- | -------- | --------------- |
| `plan`    | Yes      | `mini` or `pro` |

<CodeGroup>
  ```bash Mini plan theme={null}
  curl -X GET "https://api.pingback.live/api/v1/billing/checkout-url?plan=mini" \
    -H "Authorization: Bearer YOUR_TOKEN"
  ```

  ```bash Pro plan theme={null}
  curl -X GET "https://api.pingback.live/api/v1/billing/checkout-url?plan=pro" \
    -H "Authorization: Bearer YOUR_TOKEN"
  ```
</CodeGroup>

**Response:**

```json theme={null}
{
  "url": "https://checkout.polar.sh/checkout/..."
}
```

Redirect the user to the returned `url` to complete payment in Polar.sh.

<Note>
  Plan changes take effect immediately after checkout completes. You don't need to restart your session or re-authenticate.
</Note>

## After payment

PingBack receives a webhook from Polar.sh once your payment is confirmed. Your plan is upgraded automatically — no manual steps required. New limits for agents, channels, messages, and AI features become available right away.

## Plan limit errors

When you reach a limit on your current plan, the API returns a structured error response so you know exactly what to upgrade.

### HTTP 402 — limit exceeded

You'll receive a `402` status when you try to add more agents, channels, or KB articles than your plan allows.

```json theme={null}
{
  "error": "limit_exceeded",
  "plan": "Mini",
  "feature": "agents",
  "current": 2,
  "limit": 2,
  "message": "Upgrade to add more agents. Current plan allows 2 agents."
}
```

### HTTP 402 — feature locked

You'll receive a `feature_locked` error when you try to use a feature that isn't available on your plan. This happens, for example, when a Free plan account tries to add a non-widget channel.

```json theme={null}
{
  "error": "feature_locked",
  "plan": "Free",
  "feature": "integrations",
  "message": "Omnichannel integrations (WhatsApp, Telegram, etc) are only available on Mini and Pro plans. Free plan supports Web Widget only."
}
```

### HTTP 429 — monthly message limit

When you reach your monthly message limit, the API returns a `429` status.

```json theme={null}
{
  "error": "limit_exceeded",
  "feature": "messages",
  "current": 250,
  "limit": 250,
  "message": "Monthly message limit of 250 reached. Upgrade your plan."
}
```

## Common errors and resolutions

| Error                   | Feature         | Resolution                                              |
| ----------------------- | --------------- | ------------------------------------------------------- |
| `limit_exceeded`        | `agents`        | Upgrade to Mini (2 agents) or Pro (5 agents)            |
| `limit_exceeded`        | `channels`      | Upgrade to Mini (3 channels) or Pro (100 channels)      |
| `limit_exceeded`        | `kb_articles`   | Upgrade to Mini (25 articles) or Pro (1,000 articles)   |
| `limit_exceeded`        | `messages`      | Upgrade to a higher plan for more monthly messages      |
| `feature_locked`        | `integrations`  | Upgrade to Mini or Pro to connect omnichannel platforms |
| `feature_not_available` | `ai_auto_reply` | Upgrade to Mini or Pro to enable AI auto-reply          |

<Warning>
  Downgrading is not currently supported through the API. Contact support to request a plan downgrade.
</Warning>