Skip to main content

Upgrade Link

Get a URL an AI agent can hand to a human to upgrade the plan or add a payment method via GET /v1/billing/upgrade-link. Never charges; human-in-the-loop.

The upgrade-link endpoint (GET /v1/billing/upgrade-link) returns a URL an AI agent can hand to a human to upgrade the organization's plan or add a payment method. Plan changes and payment are deliberately a human-in-the-loop step, so this endpoint never charges anything: it returns a deep link into the dashboard billing settings plus a flag indicating a human is required.

Use it when an agent hits a wall it cannot resolve on its own: the credit balance is exhausted and auto top-up is not enabled, or the current API tier is too limiting for the workload. Instead of failing silently, the agent fetches this link and presents it to its operator with the returned message. It requires an API key with the read scope.

GET/v1/billing/upgrade-link

cURL — Fetch the upgrade link

curl https://api.talonic.com/v1/billing/upgrade-link \
  -H "Authorization: Bearer $TALONIC_API_KEY"

Response

Response fields

urlstringThe dashboard deep link to upgrade or add payment.
providerstringThe link provider: stripe (a hosted checkout session for the selected pack), dashboard (a deep link into the dashboard billing settings when checkout is unavailable), or aws_marketplace (workspaces billed through AWS Marketplace, where capacity changes go through the AWS subscription).
requires_humanbooleanAlways true. A person must complete the upgrade.
messagestringA human-readable instruction the agent can relay verbatim.
linksobjectFollow-up resources: self, billing_settings, and credits (the balance endpoint).

Response

{
  "url": "https://app.talonic.com/settings/billing?upgrade=1",
  "provider": "dashboard",
  "requires_human": true,
  "message": "Open this link to upgrade your plan or add payment. A human must complete the upgrade.",
  "links": {
    "self": "/v1/billing/upgrade-link",
    "billing_settings": "/v1/billing/settings",
    "credits": "/v1/credits/balance"
  }
}
For running low on credits (rather than changing plans), prefer the autonomous path: a human enables auto top-up once in the billing settings, and the agent keeps the balance healthy with POST /v1/billing/topup without any further human clicks.

Errors

Error responses

401unauthorizedMissing or invalid API key.
429rate_limitedToo many requests. Retry after the period indicated in the Retry-After header.

Frequently asked questions

Does this endpoint charge anything?+
No. It only returns a link a human follows to upgrade or add payment. Plan changes are human-in-the-loop by design, so the agent can never spend money or change the plan through this endpoint.
When should an agent fetch the upgrade link?+
When it hits a limit it cannot resolve autonomously: the credit balance is exhausted and auto top-up is disabled, or the workload needs a higher API tier. The agent presents the returned url and message to its human operator.
What is the difference between the upgrade link and auto top-up?+
Auto top-up (POST /v1/billing/topup) adds credits autonomously once a human has pre-authorized it in the billing settings. The upgrade link covers everything that still needs a person: upgrading the plan tier or adding a payment method.

Related

Billing Settings
Account Snapshot
Auto Top-Up
Credits Balance