Create Checkout Sessions to Onboard Subscribers

Checkout sessions are the entry point for subscribers. When a new user wants to subscribe to your service, you create a checkout session that ties together your service, the payment plan they’ve chosen, and optionally an existing user record. Retempo tracks the session through its lifecycle — from the moment it’s created until the subscriber pays and their subscription is activated (or the session expires).

Creating a checkout session

To create a checkout session, send a POST request to /api/v1/checkout-sessions with the serviceId and paymentPlanId of the plan you want to offer. Both fields are required. If you already have a user record in Retempo (for example, a returning subscriber or a pre-registered agent), pass their userId to link the session to that account. Omit userId to create an anonymous session that gets associated with a user once they complete payment.

Pass expiresAt to automatically expire sessions after a window — for example, 24 hours from creation. This prevents stale sessions from cluttering your subscriber funnel.

curl --request POST \
  --url https://api.retempo.xyz/api/v1/checkout-sessions \
  --header 'Content-Type: application/json' \
  --data '{
    "serviceId": "svc_01hx9kz3v8mq2t4yw6npd7e",
    "paymentPlanId": "plan_01hx9m1bp4nq3s8zt7vce6r",
    "userId": "usr_01hx9n2fp8qt6s3bz4wmd5k",
    "expiresAt": "2025-01-15T10:22:00.000Z"
  }'

A successful response returns the full checkout session object, including the embedded service, paymentPlan, and user objects for your convenience. Every checkout session is created with status: "PENDING" — you cannot set any other status at creation time.

{
  "checkoutSession": {
    "id": "cs_01hx9p3gq7rt8u4cz5xne6v",
    "serviceId": "svc_01hx9kz3v8mq2t4yw6npd7e",
    "paymentPlanId": "plan_01hx9m1bp4nq3s8zt7vce6r",
    "userId": "usr_01hx9n2fp8qt6s3bz4wmd5k",
    "status": "PENDING",
    "expiresAt": "2025-01-15T10:22:00.000Z",
    "createdAt": "2025-01-14T10:22:00.000Z",
    "service": {
      "id": "svc_01hx9kz3v8mq2t4yw6npd7e",
      "name": "DataStream Pro",
      "status": "ACTIVE"
    },
    "paymentPlan": {
      "id": "plan_01hx9m1bp4nq3s8zt7vce6r",
      "name": "Pro Monthly",
      "pricingType": "FIXED_RECURRING",
      "billingInterval": "MONTH",
      "amount": "49.000000",
      "currency": "USDC"
    },
    "user": {
      "id": "usr_01hx9n2fp8qt6s3bz4wmd5k",
      "email": "agent@example.io"
    }
  }
}

Checkout session lifecycle

Every checkout session starts as PENDING and moves through the following states as the subscriber takes action:

PENDING

The session has been created and is waiting for the subscriber to complete payment. This is always the initial status — you cannot create a session in any other state.

PAID

The subscriber has paid and their subscription has been activated. A subscription record is created and linked to the session. The session is now closed.

EXPIRED

The session reached its expiresAt timestamp without a completed payment. The subscriber must start a new session to subscribe.

CANCELLED

The session was explicitly cancelled before payment was completed. Like expired sessions, a cancelled session cannot be reactivated.

Fetching session status

To retrieve the current state of a checkout session — including any subscriptions that were created after payment — send a GET request with the session ID:

curl --request GET \
  --url https://api.retempo.xyz/api/v1/checkout-sessions/cs_01hx9p3gq7rt8u4cz5xne6v \
  --header 'Content-Type: application/json'

The response includes a subscriptions array that Retempo populates once the subscriber pays. Before payment, the array is empty.

{
  "checkoutSession": {
    "id": "cs_01hx9p3gq7rt8u4cz5xne6v",
    "serviceId": "svc_01hx9kz3v8mq2t4yw6npd7e",
    "paymentPlanId": "plan_01hx9m1bp4nq3s8zt7vce6r",
    "userId": "usr_01hx9n2fp8qt6s3bz4wmd5k",
    "status": "PAID",
    "expiresAt": "2025-01-15T10:22:00.000Z",
    "createdAt": "2025-01-14T10:22:00.000Z",
    "service": {
      "id": "svc_01hx9kz3v8mq2t4yw6npd7e",
      "name": "DataStream Pro",
      "status": "ACTIVE"
    },
    "paymentPlan": {
      "id": "plan_01hx9m1bp4nq3s8zt7vce6r",
      "name": "Pro Monthly",
      "pricingType": "FIXED_RECURRING",
      "billingInterval": "MONTH",
      "amount": "49.000000",
      "currency": "USDC"
    },
    "user": {
      "id": "usr_01hx9n2fp8qt6s3bz4wmd5k",
      "email": "agent@example.io"
    },
    "subscriptions": [
      {
        "id": "sub_01hx9q4hr8su9v5da6yof7w",
        "status": "ACTIVE",
        "currentPeriodStart": "2025-01-14T10:35:00.000Z",
        "currentPeriodEnd": "2025-02-14T10:35:00.000Z"
      }
    ]
  }
}

Get Started

Core Workflows

Usage Billing

Onchain Settlement

Reference

Create Checkout Sessions to Onboard Subscribers

Creating a checkout session

Checkout session lifecycle

Fetching session status

​Creating a checkout session

​Checkout session lifecycle

​Fetching session status

Creating a checkout session

Checkout session lifecycle

Fetching session status