---
title: "Start a hosted checkout."
method: POST
path: "/v1/billing/checkout"
tags: ["Billing"]
---

# Start a hosted checkout.

`POST /v1/billing/checkout`

## Request

- Base URL: `https://api.scalix.world`
- URL: `https://api.scalix.world/v1/billing/checkout`
- Auth: HTTP bearer

Creates a provider checkout session for the plan upgrade (or first
paid plan) and returns the URL to send the customer to.

## Request body

- CheckoutRequest: Hosted checkout request (upgrade / first paid plan).
  - `plan` string, required: Plan id to check out. The console sends `price_id` — accepted as an alias.
  - `success_url` string, uri, required: URL to return to after a successful payment.
  - `cancel_url` string, uri, required: URL to return to when the customer cancels.
  - `country_code` string, nullable: Customer country code (tax calculation).
  - `tenant_id` string, nullable: Tenant id; defaults to the caller's authenticated org.
  - `email` string, email, nullable: Customer email for the provider customer record.
  - `interval` string, nullable: Billing interval: "month" (default) or "year"/"annual".

## Response `201`

Checkout session created

- CheckoutSession: A hosted checkout session.
  - `session_id` string, required: Provider session id.
  - `url` string, uri, required: Hosted payment page URL.
  - `provider` string, required: Payment provider that owns the session.
  - `razorpay_key_id` string, nullable: Razorpay only: the public key id the console needs to open Checkout.js as an in-page modal.

## Other responses

- `400`: Invalid request (e.g. missing tenant/email, or the free plan)
- `401`: Missing or invalid API key
- `403`: Not your org
- `500`: Internal error

---

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