Checkout API

Checkout sessions give you programmatic control over the payment flow. Unlike static payment links, checkout sessions are generated dynamically, allowing you to:

Pass custom tracking IDs for each payment
Pre-fill customer information like email
Set dynamic success URLs based on your app’s context
Apply discount codes programmatically
Add metadata for internal tracking

Prerequisites

Before creating checkout sessions, you’ll need:

A Creem account with an API key (Get your key)
At least one product created in your dashboard. One-time products can be paid or free with a 0 price.

Find your product ID by going to the Products tab, clicking on a product, and selecting “Copy ID” from the options menu.

Creating a Checkout Session

Choose the integration method that works best for your stack:

Next.js
TypeScript SDK
Better Auth
REST API

The Next.js adapter provides a route handler and React component for seamless integration.

Install the package

npm install @creem_io/nextjs

yarn add @creem_io/nextjs

pnpm install @creem_io/nextjs

bun install @creem_io/nextjs

Create the checkout route

// app/api/checkout/route.ts
import { Checkout } from "@creem_io/nextjs";

export const GET = Checkout({
  apiKey: process.env.CREEM_API_KEY!,
  testMode: process.env.NODE_ENV !== "production",
  defaultSuccessUrl: "/success",
});

Add a checkout button

// app/page.tsx
"use client"; // Optional: CreemCheckout also works in Server Components

import { CreemCheckout } from "@creem_io/nextjs";

export function CheckoutButton() {
  return (
    <CreemCheckout
      productId="prod_YOUR_PRODUCT_ID"
      referenceId="user_123" // Optional: Track this payment in your system
    >
      <button>Buy Now</button>
    </CreemCheckout>
  );
}

The CreemCheckout component automatically handles the checkout session creation and redirects the user to the payment page.

Next.js SDK Documentation

Explore advanced features, server components, and webhook handling.

The TypeScript SDK provides full type-safety and works with any JavaScript framework.

Install the SDK

npm install creem

yarn add creem

pnpm install creem

bun install creem

Create a checkout session

import { Creem } from "creem";

const creem = new Creem({
  apiKey: process.env.CREEM_API_KEY!,
  server: process.env.NODE_ENV === "production" ? "prod" : "test",
});

// Create a checkout session
const checkout = await creem.checkouts.create({
  productId: "prod_YOUR_PRODUCT_ID",
  requestId: "order_123", // Optional: Track this payment
  successUrl: "https://yoursite.com/success",
  customer: {
    email: "customer@example.com", // Optional: Pre-fill email
  },
});

// Redirect to the checkout URL
console.log(checkout.checkoutUrl);
// In the browser: window.location.href = checkout.checkoutUrl;

TypeScript SDK Documentation

View the full SDK API reference and advanced usage examples.

The Better Auth integration automatically syncs payments with your authenticated users.

Install the plugin

npm install @creem_io/better-auth better-auth

Configure Better Auth

// auth.ts
import { betterAuth } from "better-auth";
import { creem } from "@creem_io/better-auth";

export const auth = betterAuth({
  database: {
    // your database config
  },
  plugins: [
    creem({
      apiKey: process.env.CREEM_API_KEY!,
      testMode: process.env.NODE_ENV !== "production",
      defaultSuccessUrl: "/dashboard",
    }),
  ],
});

Client setup

// lib/auth-client.ts
import { createAuthClient } from "better-auth/react";
import { creemClient } from "@creem_io/better-auth/client";

export const authClient = createAuthClient({
  baseURL: process.env.NEXT_PUBLIC_APP_URL,
  plugins: [creemClient()],
});

Create a checkout

"use client";

import { authClient } from "@/lib/auth-client";

export function CheckoutButton({ productId }: { productId: string }) {
  const handleCheckout = async () => {
    const { data, error } = await authClient.creem.createCheckout({
      productId,
      successUrl: "/dashboard",
    });

    if (data?.url) {
      window.location.href = data.url;
    }
  };

  return <button onClick={handleCheckout}>Subscribe Now</button>;
}

The Better Auth integration automatically tracks the authenticated user and syncs subscription status with your database.

Better Auth Integration

Learn about database persistence, access management, and webhook handling.

Use the REST API directly from any language or framework.

Create a checkout session

If you’re in test mode, use https://test-api.creem.io instead of https://api.creem.io. Learn more about Test Mode.

curl -X POST https://api.creem.io/v1/checkouts \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": "prod_YOUR_PRODUCT_ID",
    "request_id": "order_123",
    "success_url": "https://yoursite.com/success"
  }'

Response

{
  "id": "ch_1QyIQDw9cbFWdA1ry5Qc6I",
  "checkout_url": "https://checkout.creem.io/ch_1QyIQDw9cbFWdA1ry5Qc6I",
  "product_id": "prod_YOUR_PRODUCT_ID",
  "status": "pending"
}

Redirect your user to the checkout_url to complete the payment.

API Reference

View the complete endpoint documentation with all available parameters.

Handling Successful Payments

After a successful payment, users are redirected to your success_url with payment details as query parameters:

https://yoursite.com/success?checkout_id=ch_xxx&order_id=ord_xxx&customer_id=cust_xxx&product_id=prod_xxx

Query parameter	Description
`checkout_id`	The ID of the checkout session created for this payment.
`order_id`	The ID of the order created after successful payment.
`customer_id`	The customer ID, based on the email that executed the successful payment.
`subscription_id`	The subscription ID of the product.
`product_id`	The product ID that the payment is related to.
`request_id`	Optional. The request/reference ID you provided when creating this checkout.
`signature`	All previous parameters signed by creem using your API-key, verifiable by you.

For production applications, we recommend using Webhooks to handle payment events.

Verifying Redirect Signatures

The signature query parameter allows you to verify that the redirect came from Creem. This prevents malicious users from spoofing successful payment redirects.

The signature is a SHA-256 hex digest of the redirect parameters joined with |, with salt= {apiKey} appended at the end. Parameters appear in the order they arrive in the redirect URL (not alphabetically sorted), and null or empty values are excluded — only include parameters that have actual values.

The canonical string is built as:

key1=value1|key2=value2|...|keyN=valueN|salt={apiKey}

Then hashed with SHA-256 and hex-encoded to produce the signature value.

TypeScript
Python
Go

import * as crypto from "crypto";

interface RedirectParams {
  request_id?: string | null;
  checkout_id: string;
  order_id: string | null;
  customer_id: string | null;
  subscription_id: string | null;
  product_id: string;
  signature: string;
}

function verifyRedirectSignature(params: RedirectParams, apiKey: string): boolean {
  const { signature, ...rest } = params;

  // Keep insertion order; exclude null/undefined/empty values.
  const data = Object.entries(rest)
    .filter(([, value]) => value !== null && value !== undefined && value !== "")
    .map(([key, value]) => `${key}=${value}`)
    .concat(`salt=${apiKey}`)
    .join("|");

  const expectedSignature = crypto.createHash("sha256").update(data).digest("hex");

  return signature === expectedSignature;
}

// Usage in your success page
export async function GET(request: Request) {
  const url = new URL(request.url);

  // Read fields in the order they appear in the redirect URL.
  const params: RedirectParams = {
    request_id: url.searchParams.get("request_id"),
    checkout_id: url.searchParams.get("checkout_id")!,
    order_id: url.searchParams.get("order_id"),
    customer_id: url.searchParams.get("customer_id"),
    subscription_id: url.searchParams.get("subscription_id"),
    product_id: url.searchParams.get("product_id")!,
    signature: url.searchParams.get("signature")!,
  };

  const isValid = verifyRedirectSignature(params, process.env.CREEM_API_KEY!);

  if (!isValid) {
    return new Response("Invalid signature", { status: 401 });
  }

  // Proceed with success page...
}

import hashlib
import hmac
from urllib.parse import urlparse, parse_qsl

def verify_redirect_signature(query_string: str, api_key: str) -> bool:
    """
    Verify the redirect signature from Creem checkout.

    Args:
        query_string: The raw query string from the redirect URL.
        api_key: Your Creem API key.

    Returns:
        True if signature is valid, False otherwise.
    """
    # parse_qsl preserves the order parameters appear in the URL.
    pairs = parse_qsl(query_string, keep_blank_values=False)

    signature = ''
    parts = []
    for key, value in pairs:
        if key == 'signature':
            signature = value
            continue
        if value in (None, '', 'null'):
            continue
        parts.append(f'{key}={value}')

    parts.append(f'salt={api_key}')
    data = '|'.join(parts)

    expected_signature = hashlib.sha256(data.encode()).hexdigest()
    return hmac.compare_digest(signature, expected_signature)

# Usage in Flask
@app.route('/success')
def success():
    if not verify_redirect_signature(request.query_string.decode(), os.environ['CREEM_API_KEY']):
        return 'Invalid signature', 401

    # Proceed with success page...

package main

import (
    "crypto/sha256"
    "crypto/subtle"
    "encoding/hex"
    "net/url"
    "strings"
)

// verifyRedirectSignature checks the redirect signature using the raw query
// string so parameter order matches what Creem signed.
func verifyRedirectSignature(rawQuery, apiKey string) bool {
    var signature string
    var parts []string

    for _, pair := range strings.Split(rawQuery, "&") {
        if pair == "" {
            continue
        }
        key, value, _ := strings.Cut(pair, "=")
        decodedKey, err := url.QueryUnescape(key)
        if err != nil {
            return false
        }
        decodedValue, err := url.QueryUnescape(value)
        if err != nil {
            return false
        }

        if decodedKey == "signature" {
            signature = decodedValue
            continue
        }
        if decodedValue == "" || decodedValue == "null" {
            continue
        }
        parts = append(parts, decodedKey+"="+decodedValue)
    }

    parts = append(parts, "salt="+apiKey)
    data := strings.Join(parts, "|")

    sum := sha256.Sum256([]byte(data))
    expected := hex.EncodeToString(sum[:])

    return subtle.ConstantTimeCompare([]byte(signature), []byte(expected)) == 1
}

Important: Parameters with null or empty values (like order_id for subscription-only checkouts, or subscription_id for one-time payments) must be excluded from the signed string. Including them as "order_id=null" will cause verification to fail.

Advanced Features

Metadata

Add custom metadata to track additional information with each payment. Metadata is included in webhook events and can be retrieved later.

Next.js
TypeScript SDK
Better Auth
REST API

<CreemCheckout
  productId="prod_YOUR_PRODUCT_ID"
  referenceId="user_123"
  metadata={{
    userId: "internal_user_id",
    planType: "premium",
    source: "marketing_campaign",
  }}
>
  <button>Subscribe</button>
</CreemCheckout>

const checkout = await creem.checkouts.create({
  productId: "prod_YOUR_PRODUCT_ID",
  requestId: "order_123",
  metadata: {
    userId: "internal_user_id",
    planType: "premium",
    source: "marketing_campaign",
  },
});

const { data } = await authClient.creem.createCheckout({
  productId: "prod_YOUR_PRODUCT_ID",
  metadata: {
    planType: "premium",
    source: "marketing_campaign",
  },
});

curl -X POST https://api.creem.io/v1/checkouts \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": "prod_YOUR_PRODUCT_ID",
    "metadata": {
      "userId": "internal_user_id",
      "planType": "premium",
      "source": "marketing_campaign"
    }
  }'

Metadata is especially useful for tracking internal IDs, campaign sources, or any custom information you need to associate with a payment.

Custom Success URL

Override the default success URL on a per-checkout basis. This is useful for directing users to specific pages after payment based on context.

Next.js
TypeScript SDK
Better Auth
REST API

<CreemCheckout
  productId="prod_YOUR_PRODUCT_ID"
  successUrl="/account/welcome" // Overrides defaultSuccessUrl
>
  <button>Get Started</button>
</CreemCheckout>

const checkout = await creem.checkouts.create({
  productId: "prod_YOUR_PRODUCT_ID",
  successUrl: "https://yoursite.com/account/welcome",
});

const { data } = await authClient.creem.createCheckout({
  productId: "prod_YOUR_PRODUCT_ID",
  successUrl: "/account/welcome",
});

curl -X POST https://api.creem.io/v1/checkouts \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": "prod_YOUR_PRODUCT_ID",
    "success_url": "https://yoursite.com/account/welcome"
  }'

Pre-fill Customer Email

Lock the customer email at checkout to ensure users complete payment with the email they registered with on your platform.

Next.js
TypeScript SDK
Better Auth
REST API

<CreemCheckout productId="prod_YOUR_PRODUCT_ID" customer={{ email: "user@example.com" }}>
  <button>Complete Purchase</button>
</CreemCheckout>

const checkout = await creem.checkouts.create({
  productId: "prod_YOUR_PRODUCT_ID",
  customer: {
    email: "user@example.com",
  },
});

// Email is automatically set from the authenticated user
const { data } = await authClient.creem.createCheckout({
  productId: "prod_YOUR_PRODUCT_ID",
  customer: {
    email: "user@example.com", // Optional: if you want to overwrite the session
  },
});

The Better Auth integration automatically uses the authenticated user’s email.

curl -X POST https://api.creem.io/v1/checkouts \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": "prod_YOUR_PRODUCT_ID",
    "customer": {
      "email": "user@example.com"
    }
  }'

Apply Discount Codes

Apply discount codes programmatically to pre-fill them at checkout.

Next.js
TypeScript SDK
Better Auth
REST API

<CreemCheckout productId="prod_YOUR_PRODUCT_ID" discountCode="LAUNCH50">
  <button>Claim Offer</button>
</CreemCheckout>

const checkout = await creem.checkouts.create({
  productId: "prod_YOUR_PRODUCT_ID",
  discountCode: "LAUNCH50",
});

const { data } = await authClient.creem.createCheckout({
  productId: "prod_YOUR_PRODUCT_ID",
  discountCode: "LAUNCH50",
});

curl -X POST https://api.creem.io/v1/checkouts \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": "prod_YOUR_PRODUCT_ID",
    "discount_code": "LAUNCH50"
  }'

Discount Codes

Learn how to create and manage discount codes in your dashboard.

Seat-Based Billing

Charge for multiple units or seats by specifying the units parameter. The total price will be calculated as base_price × units.

Next.js
TypeScript SDK
Better Auth
REST API

<CreemCheckout
  productId="prod_YOUR_PRODUCT_ID"
  units={seatCount} // Charge for 5 seats
>
  <button>Add {seatCount} Seats</button>
</CreemCheckout>

const checkout = await creem.checkouts.create({
  productId: "prod_YOUR_PRODUCT_ID",
  units: 5, // Charge for 5 seats
});

const { data } = await authClient.creem.createCheckout({
  productId: "prod_YOUR_PRODUCT_ID",
  units: 5, // Charge for 5 seats
});

curl -X POST https://api.creem.io/v1/checkouts \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": "prod_YOUR_PRODUCT_ID",
    "units": 5
  }'

Seat-Based Billing

Learn more about implementing and managing seat-based pricing models.

Next Steps

Checkout Customization

Brand your checkout with custom colors, logos, and themes

Checkout Custom Fields

Collect additional information from customers during checkout

Subscriptions

Learn how to manage recurring billing and subscriptions

Revenue Splits

Split revenue between multiple parties automatically

​Prerequisites

​Creating a Checkout Session

​Install the package

​Create the checkout route

​Add a checkout button

Next.js SDK Documentation

​Install the SDK

​Create a checkout session

TypeScript SDK Documentation

​Install the plugin

​Configure Better Auth

​Client setup

​Create a checkout

Better Auth Integration

​Create a checkout session

​Response

API Reference

​Handling Successful Payments

​Verifying Redirect Signatures

​Advanced Features

​Metadata

​Custom Success URL

​Pre-fill Customer Email

​Apply Discount Codes

Discount Codes

​Seat-Based Billing

Seat-Based Billing

​Next Steps

Checkout Customization

Checkout Custom Fields

Subscriptions

Revenue Splits

Prerequisites

Creating a Checkout Session

Install the package

Create the checkout route

Add a checkout button

Install the SDK

Create a checkout session

Install the plugin

Configure Better Auth

Client setup

Create a checkout

Create a checkout session

Response

Handling Successful Payments

Verifying Redirect Signatures

Advanced Features

Metadata

Custom Success URL

Pre-fill Customer Email

Apply Discount Codes

Seat-Based Billing

Next Steps