.svg?fit=max&auto=format&n=vy0mukkT7J4oGoAc&q=85&s=309fd13aafaa2459ab88bae66ee69fdb)
.svg?fit=max&auto=format&n=vy0mukkT7J4oGoAc&q=85&s=d463f8e401c13f13ee15256db8c610dd)
Credits
Create Credit Top-Up
Start a credit top-up — returns a Stripe Checkout URL a human must pay. Nothing is charged by this call.
POST
Starts a prepaid credit top-up. This call never charges anything. It creates a
PENDING top-up and returns a Stripe Checkout checkoutUrl that a signed-in human must open and pay; once checkout completes, the credits land automatically. The link expires unpaid after ~24 hours (expiresAt).
Learn the outcome by polling GET /credits/top-ups/{topUpId} until the status is COMPLETED, then confirm the new balance with GET /credits.
Requirements: payments:write scope + the public_api_credits feature + a claimed account (unclaimed accounts get 403 with details.reason: "account_claim_required" and a claimUrl).
Request
Top-up amount in US dollars. Minimum 10,000. (
amount is accepted as an alias.)Response
Returns201 — the top-up exists, but no money has moved until the human pays the checkout link.
The top-up ID, for polling.
Stripe Checkout URL — show it to your human so they can complete the payment.
ISO timestamp when the unpaid checkout link lapses (~24h).
The full top-up record:
{id, status: "PENDING", amountCents, createdAt, completedAt, expiresAt} — same shape as GET /credits/top-ups/{topUpId}.Explains the human-payment handoff.