Start a wallet top-up Checkout session
Creates a Stripe-hosted Checkout session for a one-time wallet top-up.
Redirect the browser to the returned checkout_url; on success your
wallet is credited with the chosen amount.
success_url and cancel_url are both required and must use HTTPS in
production.
Error responses:
404 NOT_FOUND(NO_PLAN) when your organization has no subscription; top-up requires an active plan.422 VALIDATION_FAILEDwithdetails.stripe_product_idwhen the top-up option is unknown or unavailable.402 BELOW_MINIMUM_CREDITwhen the amount is below your plan'smin_topup_centsfloor. Under PAYG that floor isNULL, so every SKU ($5–$100) is accepted and this branch does not trip.
Requires the billing:write scope. The top-up applies to the
authenticated organization; the route does not accept an organization id.
Authenticate by sending your API key as a bearer token:
Authorization: Bearer am_live_.... Every request is automatically
scoped to the organization that owns the key and to the scopes granted
to that key.
In: header
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/v1/billing/topup" \ -H "Content-Type: application/json" \ -d '{ "stripe_product_id": "prod_UNRcByVTMJ9LH2", "success_url": "https://app.example.com/billing/topup/success?session_id={CHECKOUT_SESSION_ID}", "cancel_url": "https://app.example.com/billing/topup/cancel" }'{
"success": true,
"data": {
"checkout_session_id": "cs_test_a1b2c3d4",
"checkout_url": "https://checkout.stripe.com/c/pay/cs_test_a1b2c3d4"
}
}{
"success": false,
"error": {
"code": "UNAUTHORIZED",
"message": "authentication failed",
"request_id": "01JTBQH2FZ8K1RXC0WJ4Z9P3VM"
}
}{
"success": false,
"error": {
"code": "BELOW_MINIMUM_CREDIT",
"message": "balance below tier minimum",
"request_id": "01JTBQH2FZ8K1RXC0WJ4Z9P3VM"
}
}{
"success": false,
"error": {
"code": "FORBIDDEN",
"message": "missing required scope",
"request_id": "01JTBQH2FZ8K1RXC0WJ4Z9P3VM"
}
}{
"success": false,
"error": {
"code": "NO_PLAN",
"message": "subscription plan required",
"request_id": "01JTBQH2FZ8K1RXC0WJ4Z9P3VM"
}
}{
"success": false,
"error": {
"code": "VALIDATION_FAILED",
"message": "validation failed",
"request_id": "01JTBQH2FZ8K1RXC0WJ4Z9P3VM",
"details": {
"to": "must be E.164",
"body": "must be 1..1600 chars"
}
}
}