Skip to main content
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

​
serviceId
string
required
The ID of the service the subscriber is signing up for.
​
paymentPlanId
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.
​
userId
string
The ID of an existing Retempo user to pre-associate with this session. If omitted, the user is identified during the checkout flow.
​
expiresAt
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.
​
checkoutSession
object
The newly created checkout session.

​
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

StatusMessageCondition
400 Bad RequestserviceId is required.serviceId was omitted.
400 Bad RequestpaymentPlanId is required.paymentPlanId was omitted.
400 Bad RequestCheckout sessions can only be created with PENDING status.A non-PENDING value was passed for status.
404 Not FoundPayment plan was not found for the service.The plan does not exist or does not belong to the specified service.
404 Not FoundReferenced 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.