Upgrading

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`

curl -X GET "https://api.pingback.live/api/v1/billing/checkout-url?plan=mini" \
  -H "Authorization: Bearer YOUR_TOKEN"

curl -X GET "https://api.pingback.live/api/v1/billing/checkout-url?plan=pro" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response:

{
  "url": "https://checkout.polar.sh/checkout/..."
}

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

Plan changes take effect immediately after checkout completes. You don’t need to restart your session or re-authenticate.

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.

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

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

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

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

Get Started

Core Concepts

Channels

AI Assistant

Realtime & Webhooks

Plans & Billing

Get a checkout URL

After payment

Plan limit errors

HTTP 402 — limit exceeded

HTTP 402 — feature locked

HTTP 429 — monthly message limit

Common errors and resolutions

​Get a checkout URL

​After payment

​Plan limit errors

​HTTP 402 — limit exceeded

​HTTP 402 — feature locked

​HTTP 429 — monthly message limit

​Common errors and resolutions

Get a checkout URL

After payment

Plan limit errors

HTTP 402 — limit exceeded

HTTP 402 — feature locked

HTTP 429 — monthly message limit

Common errors and resolutions