---
title: "Creates a checkout session for a plan or a token top-up."
method: POST
path: "/api/billing/checkout"
tags: ["billing"]
---

# Creates a checkout session for a plan or a token top-up.

`POST /api/billing/checkout`

## Request

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

## Request body

- CreateCheckoutRequest: Request body for `POST /api/billing/checkout`.
  - `cancel_url` string, required: URL the buyer is redirected to when they cancel the checkout.
  - `locale` string, nullable: Language of the hosted checkout page and of the terms the buyer accepts there (`"en"` or `"fr"`).
  - `success_url` string, required: URL the buyer is redirected to after a successful payment.
  - `target` union, required: Checkout target from the request body.
    - object: Subscribe to a plan.
      - `cycle` string, required: Billing cycle (`"monthly"` or `"yearly"`).
      - `plan` string, required: Plan code (e.g. `"starter"`, `"pro"`, `"business"`, `"enterprise"`).
      - `type` 'plan', required
    - object: One-time credit top-up.
      - `token_quantity` integer, required: Number of tokens to purchase.
      - `type` 'top_up', required

## Response `200`

Hosted checkout redirect URL.

- CheckoutSessionResponse: JSON response body for `POST /api/billing/checkout`.
  - `url` string, required: Hosted checkout URL to redirect the user to.

## Other responses

- `400`: Unrecognized plan code, billing cycle, top-up quantity, or locale.
- `401`: Missing or invalid JWT.
- `409`: Caller already has an active paid subscription.
- `503`: Billing is not available.

---

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