Skip to main content
POST
Create a top-up checkout
Top up credits against the caller’s personal balance or an organization’s shared team billing pool. Returns a hosted checkout URL your application opens in a new tab or redirects the user to.

Authentication

Requires a Bearer token with the billing scope. See Authentication.

Body

integer
required
Amount to add, in cents. Minimum 500 (5.00),maximum100000(5.00), maximum `100000` (1,000.00).
string
"user" (default when personal) or "org" (default when the caller is inside a team and holds manageBilling). When "org", the top-up lands on the team’s shared credit pool at organizations.polar_customer_id and all subsequent team-scoped API usage draws from that pool until it’s depleted.
string
Optional. URL to redirect the user to after successful checkout. Defaults to /dashboard/billing?topup=success (or /dashboard/billing?topup=success&scope=team when scope: "org").

Example: personal top-up

curl

Example: team top-up

curl
SDK

Response

Errors

Lifecycle

  1. Client calls this endpoint with amount_cents and optional scope.
  2. The billing service reserves the right customer (personal or team), creates a checkout session, and returns checkout_url.
  3. The user completes checkout.
  4. A background webhook routes the top-up to the correct credit pool (user vs team) and marks the customer as having a payment method on file.
  5. Subsequent API usage drafts from the funded pool.