Create checkout session

Create a checkout session for plan subscription

Create checkout session

Create a secure checkout session for subscribing to a plan. This redirects the user to a payment page where they can complete their subscription.

Endpoint

createCheckoutSession(params: CreateCheckoutParams): Promise<CheckoutResponse>

Route: POST /payment/checkout

Parameters

planId · string · required

The ID of the plan to subscribe to

Request body

interface CreateCheckoutParams {
  planId: string;
}

Response

success · boolean

Whether the checkout session was created successfully

data · object

Show properties

checkoutUrl · string

The URL to redirect the user to for payment

checkoutId · string

Unique identifier for this checkout session

expiresAt · string

ISO 8601 timestamp when the checkout session expires

message · string

Human-readable status message

Example

TypeScript

import { createCheckoutSession } from '@/lib/api/payment';

const response = await createCheckoutSession({
  planId: 'plan_professional'
});

if (response.success) {
  // Redirect user to checkout
  window.location.href = response.data.checkoutUrl;
}

Response example

{
  "success": true,
  "data": {
    "checkoutUrl": "https://checkout.stripe.com/c/pay/cs_test_...",
    "checkoutId": "cs_test_a1b2c3d4e5f6",
    "expiresAt": "2024-12-31T23:59:59Z"
  },
  "message": "Checkout session created successfully"
}

Error responses

400 - Invalid plan ID

{
  "success": false,
  "message": "Invalid plan ID provided"
}

401 - Unauthorized

{
  "success": false,
  "message": "Authentication required"
}

404 - Plan not found

{
  "success": false,
  "message": "Plan not found or inactive"
}

Checkout flow

1. Create session - Call this endpoint with the desired plan ID
2. Redirect user - Redirect to the checkoutUrl from the response
3. User completes payment - User enters payment information on the secure checkout page
4. Redirect back - User is redirected back to your success URL
5. Webhook notification - Your backend receives a webhook confirming the subscription

Checkout sessions expire after 24 hours. If the user doesn’t complete payment within this time, they’ll need to create a new session.

Get checkout session

Retrieve an existing checkout session by ID:

getCheckoutSession(id: string): Promise<CheckoutResponse>

Route: GET /payment/checkout/{id}

This is useful for checking the status of a checkout session or recovering from interrupted flows.

Next steps

Manage subscription

View and manage active subscriptions

Payment history

Access transaction history