---
title: "Create Checkout Session"
method: POST
path: "/v1/checkout-session"
tags: ["Billing"]
---

# Create Checkout Session

`POST /v1/checkout-session`

## Request

- Base URL: `https://api.fettle.sh` (the document declares no server; this is the origin it was published from)
- URL: `https://api.fettle.sh/v1/checkout-session`
- Auth: API key in header `Authorization`

Start a checkout to upgrade the active organization to a paid plan.

The request body selects a monthly or yearly product for the chosen plan.
Returns a hosted checkout URL to redirect the user to. The plan activates
once payment completes and the subscription webhook is received.

## Headers

- `X-Organization-Id` string, uuid, nullable

## Request body

- CheckoutSessionRequest: Request body for ``POST /v1/checkout-session``. ``billing_period`` defaults to ``MONTH`` on purpose: core deploys ahead of the frontend, so during that window the older client posts no period at all and must keep buying monthly plans rather than failing validation.
  - `plan` 'FREE' | 'PLUS' | 'PRO' | 'MAX' | 'ENTERPRISE', required: Subscription tier of an organization; gates feature/usage limits.
  - `billing_period` 'MONTH' | 'YEAR': How often a subscription renews. Polar models monthly and yearly billing as separate products, so the period is part of what a checkout selects. Member name == value to match the project's enum convention and the persisted DB labels.
  - `success_url` string, uri, required
  - `cancel_url` string, uri, required

## Response `200`

Successful Response

- CheckoutSessionResponse
  - `checkout_id` string, required
  - `redirect_url` string, uri, required

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/fettle/apis/fettle-sh.md) · [All operations](https://skmtc.dev/fettle/apis/fettle-sh/llms.txt) · [OpenAPI document](https://skmtc.dev/fettle/apis/fettle-sh/revisions/f32c8a18606f?raw)