---
title: "Create Stripe Checkout subscription session"
method: POST
path: "/billing/checkout-session"
---

# Create Stripe Checkout subscription session

`POST /billing/checkout-session`

## Request

- Base URL: `https://api.gravityads.dev` (the document declares no server; this is the origin it was published from)
- URL: `https://api.gravityads.dev/billing/checkout-session`
- Auth: HTTP bearer

## Request body

- object
  - `plan_id` string, required
  - `catalog_version` string
  - `account_count` integer
  - `billing_interval` 'monthly' | 'annual'
  - `request_key` string
  - `success_url` string, uri, required
  - `cancel_url` string, uri, required
  - `customer_id` string
  - `quantity` integer
  - `promotion_code` string
  - `allow_promotion_codes` boolean
  - `metadata` object

## Response `200`

Checkout session

- object
  - `status` 'stripe_checkout_session_created' | 'stripe_checkout_setup_required' | 'stripe_checkout_session_failed', required
  - `tenant_id` string
  - `plan_id` string
  - `session_id` string
  - `url` string
  - `client_secret` string
  - `mode` string
  - `payment_status` string
  - `error_code` string
  - `retry` boolean
  - `raw_secrets_returned` false, required
  - `subscription` object
  - `customer_id_source` 'request' | 'control_plane_subscription' | 'none'
  - `hosted_auth_context` object
  - `message` string
  - `billing_setup_required` boolean
  - `self_service_checkout_ready` false
  - `payment_collection_blocked` boolean
  - `tenant_bootstrapped` boolean
  - `internal_trial_active` boolean
  - `safe_to_continue_read_only_setup` boolean
  - `next_actions` object[]
    - `id` string, required
    - `status` string, required
    - `owner` string
    - `path` string
    - `requires` string[]
    - `url_present` boolean
    - `session_id` string
  - `raw_price_ids_returned` false

## Other responses

- `503`: Checkout setup required or Stripe unavailable

---

[API](https://skmtc.dev/gravityads/apis/gravityads-api.md) · [All operations](https://skmtc.dev/gravityads/apis/gravityads-api/llms.txt) · [OpenAPI document](https://skmtc.dev/gravityads/apis/gravityads-api/revisions/124cd07d534d?raw)