> ## Documentation Index
> Fetch the complete documentation index at: https://docs.retempo.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Checkout Sessions to Onboard Subscribers

> Use Retempo checkout sessions to onboard new subscribers to your service. Sessions link a payment plan to a user and track payment status.

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.

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

```curl theme={null}
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.

```json theme={null}
{
  "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:

<Steps>
  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="EXPIRED">
    The session reached its `expiresAt` timestamp without a completed payment. The subscriber must start a new session to subscribe.
  </Step>

  <Step title="CANCELLED">
    The session was explicitly cancelled before payment was completed. Like expired sessions, a cancelled session cannot be reactivated.
  </Step>
</Steps>

## 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 theme={null}
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.

```json theme={null}
{
  "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"
      }
    ]
  }
}
```