Skip to main content
POST
Create a Stripe Checkout session

Authorizations

Authorization
string
header
required

Short-lived JWT issued by the CarHub auth service (Better Auth), verified against its JWKS. Claims: sub (user), org_id (active organisation) and role (owner | admin | member). Used by the dashboard for /mgmt/v1/… only — it is never accepted on /v1/….

Headers

Idempotency-Key
string

Client-generated key (a UUID is ideal) making this POST safe to retry. The first request is executed and its response stored for 24 h; any replay with the same key returns that stored response with Idempotent-Replayed: true and bills nothing. Reusing a key with a different payload is a 409 idempotency_key_reuse.

Required string length: 8 - 255

Body

application/json
mode
enum<string>
required

top_up adds money once; subscription starts a recurring plan.

Available options:
top_up,
subscription
price_id
string
required

Identifier of the pack or plan, resolved against the price book of your billing country.

Example:

"pack_10k"

success_url
string<uri>
required
cancel_url
string<uri>
required
quantity
integer
default:1
Required range: 1 <= x <= 100

Response

Session created; redirect the browser to url.

url
string<uri>
required

Stripe-hosted page to redirect the browser to.

object
string
required
Allowed value: "checkout_session"
id
string
Example:

"cs_test_a1B2c3D4"

expires_at
integer<int64>

Epoch seconds, UTC.

Example:

1755300000

mode
enum<string>
Available options:
top_up,
subscription