Create Checkout Sessions

Use a checkout session when your backend needs to choose products, identity, pricing, metadata, or redirect behavior immediately before the buyer pays.

Start from your server

Call Create Checkout Session with at least one product identifier. Ruba returns the session record and its temporary url; redirect the buyer to that URL.

TypeScript

import { Ruba } from "@getruba/sdk";

const ruba = new Ruba({ accessToken: process.env.RUBA_ACCESS_TOKEN ?? "" });
const checkout = await ruba.checkouts.create({ products: ["<product_id>"] });

console.log(checkout.url);

Append ?theme=light or ?theme=dark to override the system color preference for that visit.

Offer several products

Pass products in the order they should appear. Checkout displays a product selector, but the final order still contains one selected product.

Create session-only prices

The prices map can replace catalog pricing for this session. Each key is a product ID and each value is an array of price definitions created only for this checkout. Use this for a customer-specific quote, calculated amount, temporary experiment, or price tier that should not become a catalog price. Session-only prices return source: "ad_hoc"; normal product prices return source: "catalog".

TypeScript

const checkout = await ruba.checkouts.create({
  products: ["<product_id>"],
  prices: {
    "<product_id>": [{
      amountType: "fixed",
      priceAmount: 10000,
      priceCurrency: "usd",
    }],
  },
});

Fixed, pay-what-you-want, free, member-priced, and metered definitions are accepted. Use the operation schema for their exact fields.

Bind checkout to your customer model

Send external_customer_id when your application already owns the canonical customer identifier. After a successful checkout, Ruba stores it on the customer and includes it in customer webhook payloads. Sending either customer_id or external_customer_id also locks the prefilled email field, ensuring the purchase cannot be moved to another identity in the browser.

Preserve country detection through a backend

Country affects local currency selection, billing-country defaults, and tax calculation. Ruba normally derives it from the request that creates checkout. That request originates from your infrastructure when you use a backend, proxy, edge function, or route handler. Pass the buyer’s address as customer_ip_address so Ruba does not mistake the server location for the buyer location.

TypeScript

const checkout = await ruba.checkouts.create({
  products: ["<product_id>"],
  customerIpAddress: request.headers.get("CF-Connecting-IP") ?? undefined,
});

Cloudflare commonly exposes CF-Connecting-IP; traditional proxies commonly use x-forwarded-for; FastAPI exposes the connected host through request.client.host. When customer_ip_address is present, you do not also need to supply the billing country for detection.

Continue from the returned session

Store any reference metadata your application needs, redirect to url, and treat checkout or order webhooks as the authoritative completion signal. The session itself expires, so never publish its URL as a permanent buy link.

Launch Path

Shape the Offer

Run the Revenue Model

Deliver Customer Access

Build the Integration

Operate the Business

Implementation Playbooks

Create Checkout Sessions

Start from your server

Offer several products

Create session-only prices

Bind checkout to your customer model

Preserve country detection through a backend

Continue from the returned session

​Start from your server

​Offer several products

​Create session-only prices

​Bind checkout to your customer model

​Preserve country detection through a backend

​Continue from the returned session

Start from your server

Offer several products

Create session-only prices

Bind checkout to your customer model

Preserve country detection through a backend

Continue from the returned session