---
title: "Create a checkout session"
method: POST
path: "/v1/sdk/checkout-sessions"
tags: ["Checkout Sessions"]
---

# Create a checkout session

`POST /v1/sdk/checkout-sessions`

Creates a hosted checkout session for a customer to purchase a product plan, or to top up credits (`purpose: "credit_topup"`, which skips `productRef`). Returns a session ID and checkout URL for redirect.

## Request body

- CreateCheckoutSessionRequest
  - `customerRef` string, required
  - `planRef` string
  - `productRef` string
  - `purpose` 'credit_topup'
  - `returnUrl` string

## Response `201`

Checkout session created

- CreateCheckoutSessionResponse
  - `checkoutUrl` string, required — Full checkout URL based on backend configuration (ready to redirect customer)
  - `sessionId` string, required — Checkout session ID/token

## Other responses

- `400` — Missing customerRef or productRef

## Changes

- **2026-07-17** `bbc2ff2bc849` — 3 warning
  - the `customerRef` request property's maxLength was set to `20`
  - the `planRef` request property's maxLength was set to `20`
  - the `productRef` request property's maxLength was set to `20`
- **2026-07-04** `a30b6aef464d` — 2 info
  - the endpoint scheme security `SecretKey` was added to the API
  - the endpoint scheme security `bearer` was removed from the API
- **2026-04-04** `88abf6f50f11` — 2 breaking, 4 info
  - the `customerRef` request property's minLength was increased from `0` to `1`
  - the `productRef` request property's minLength was increased from `0` to `1`
  - added the new optional request property `purpose`
  - the request property `productRef` became optional
  - …2 more
- **2026-02-27** `9079f361f51c` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/solvapay/apis/solvapay-rest-api/changes/v1/sdk/checkout-sessions/post.md)

---

[API](https://skmtc.dev/solvapay/apis/solvapay-rest-api.md) · [All operations](https://skmtc.dev/solvapay/apis/solvapay-rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/solvapay/solvapay-rest-api/revisions/d29ab7373802/schema)