billing.create_portal_session

Open the self-service billing portal for an organization

Request: POST/api/v1/organizations/{organizationSlug}/billing/portal-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_portal_session
Environment: Live and sandbox alike.
Request body: JSON.

What it does

Answers with a URL on the payment provider’s own customer portal, where an owner changes the seat count, updates the card or cancels. A person has to open it; nothing changes until they act there, and the seat count follows once the change clears. Owners only, and an organization with no subscription yet is refused with 409 — start one with `billing.create_checkout_session`. A **sandbox** credential never reaches the payment provider; it gets a URL on our own documentation site describing what the live call would have done. 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

Response

url: string, required

Examples

Send an owner to manage their subscription

Send an owner to manage their subscription — request

curl -s -X POST https://www.jobapplicationtracking.com/api/v1/organizations/northside-career-center/billing/portal-session \
  -H "Authorization: Bearer $JAT_KEY"

Send an owner to manage their subscription — response

{
  "url": "https://billing.stripe.com/p/session/live_a1b2c3"
}