POST /api/v1/checkout-sessions — Create Checkout Session

A checkout session is the entry point for subscriber onboarding. You create one by linking a service to a payment plan, and optionally pre-associating an existing user. Retempo always creates the session in PENDING status and returns it immediately — the session transitions to PAID only after the subscriber completes payment.

POST https://api.retempo.xyz/api/v1/checkout-sessions

Request Body

string

required

The ID of the service the subscriber is signing up for.

string

required

The ID of the payment plan to attach to this checkout session. The plan must belong to the specified service; a mismatch returns a 404.

string

The ID of an existing Retempo user to pre-associate with this session. If omitted, the user is identified during the checkout flow.

string

An ISO 8601 datetime string specifying when the session expires. If omitted, the session does not expire automatically.

Response

A successful request returns HTTP 201 Created with the new checkout session object. The status is always PENDING.

object

The newly created checkout session.

Show checkoutSession fields

string

Unique identifier for the checkout session.

string

ID of the associated service.

string

ID of the associated payment plan.

string | null

ID of the pre-associated user, or null if not yet known.

string

Always PENDING on creation.

string | null

Expiry datetime, or null if not set.

string

ISO 8601 datetime the session was created.

object

Nested service object with id, name, and status.

object

Nested payment plan with id, name, amount, and currency.

object | null

Nested user object if userId was provided, otherwise null.

201 — Checkout session created

{
  "checkoutSession": {
    "id": "clz1checkout789",
    "serviceId": "clz1abc2def3ghi4",
    "paymentPlanId": "clz1plan567",
    "userId": null,
    "status": "PENDING",
    "expiresAt": "2025-06-02T10:00:00.000Z",
    "createdAt": "2025-06-01T10:10:00.000Z",
    "service": {
      "id": "clz1abc2def3ghi4",
      "name": "DataStream Pro",
      "status": "ACTIVE"
    },
    "paymentPlan": {
      "id": "clz1plan567",
      "name": "Pro Monthly",
      "amount": "49.000000",
      "currency": "USDC"
    },
    "user": null
  }
}

Example Request

curl -X POST https://api.retempo.xyz/api/v1/checkout-sessions \
  -H "Content-Type: application/json" \
  -d '{
    "serviceId": "clz1abc2def3ghi4",
    "paymentPlanId": "clz1plan567",
    "expiresAt": "2025-06-02T10:00:00.000Z"
  }'

Error Codes

Status	Message	Condition
`400 Bad Request`	`serviceId is required.`	`serviceId` was omitted.
`400 Bad Request`	`paymentPlanId is required.`	`paymentPlanId` was omitted.
`400 Bad Request`	`Checkout sessions can only be created with PENDING status.`	A non-`PENDING` value was passed for `status`.
`404 Not Found`	`Payment plan was not found for the service.`	The plan does not exist or does not belong to the specified service.
`404 Not Found`	`Referenced database record was not found.`	The `userId` was not found.

Checkout sessions are always created with status PENDING. The session transitions to PAID when the subscriber completes payment. Attempting to create a session with any other initial status returns a 400 error.

Overview

Services

Payment Plans

Checkout & Invoicing

Settlements

POST /api/v1/checkout-sessions — Create Checkout Session

Request Body

Response

201 — Checkout session created

Example Request

Error Codes

​Request Body

​Response

​201 — Checkout session created

​Example Request

​Error Codes

Request Body

Response

201 — Checkout session created

Example Request

Error Codes