billing.create_checkout_session

Start buying seats for an organization

Request: POST/api/v1/organizations/{organizationSlug}/billing/checkout-session
Scope required: billing:write
Effect: Changes data. Send an Idempotency-Key if you might retry it.
Acts on: Acts on an organization, and names it in the path.
MCP tool: billing_create_checkout_session
Environment: Live and sandbox alike.
Request body: JSON.

What it does

Answers with a URL on the payment provider’s own checkout page, which a person has to open and complete — nothing is charged here, and the seat count only changes once the payment clears. Owners only. An organization that already has a live subscription is refused with 409: change the seat count through `billing.create_portal_session` instead. A **sandbox** credential never reaches the payment provider at all; it gets a URL on our own documentation site describing what the live call would have done, so an integration can be exercised end to end without anybody spending anything. A sandbox organization has no subscription state to be in, so the 409 above never fires there — only the owners-only check does. Do not write a test that expects it in sandbox.

Parameters

Parameters this endpoint accepts, where each one goes, and whether it is required
Name	Sent in	Requirement	Accepts
organizationSlug	path	Required	string

Request body

interval: one of: monthly, annual, required
seats: integer, required

Response

url: string, required

Examples

Buy twenty seats billed monthly

Buy twenty seats billed monthly — request

curl -s -X POST https://www.jobapplicationtracking.com/api/v1/organizations/northside-career-center/billing/checkout-session \
  -H "Authorization: Bearer $JAT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "seats": 20,
  "interval": "monthly"
}'

Buy twenty seats billed monthly — response

{
  "url": "https://checkout.stripe.com/c/pay/cs_live_a1b2c3"
}