Skip to main content
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:
ParameterRequiredValues
planYesmini or pro
curl -X GET "https://api.pingback.live/api/v1/billing/checkout-url?plan=mini" \
  -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

ErrorFeatureResolution
limit_exceededagentsUpgrade to Mini (2 agents) or Pro (5 agents)
limit_exceededchannelsUpgrade to Mini (3 channels) or Pro (100 channels)
limit_exceededkb_articlesUpgrade to Mini (25 articles) or Pro (1,000 articles)
limit_exceededmessagesUpgrade to a higher plan for more monthly messages
feature_lockedintegrationsUpgrade to Mini or Pro to connect omnichannel platforms
feature_not_availableai_auto_replyUpgrade to Mini or Pro to enable AI auto-reply
Downgrading is not currently supported through the API. Contact support to request a plan downgrade.