Checkout

If you want to integrate the checkout process directly into your application, you can use our API to create sessions programmatically. This gives you full control over when and how your customers are prompted to pay.

Checkout isn’t just for one-time payments - when a customer completes checkout, Paid creates an order (subscription) that tracks their plan, billing cycle, and usage over time.

You’ll need a Product ID to get started. You can find it in the Products section of your dashboard, or create one via the API.

Creating a session

To create a checkout session, call the API with the products you want the customer to purchase and a URL to redirect them to after payment.

The API returns an object containing all the information about the session, including a url where you should redirect your customer so they can complete their order.

1
import { PaidClient } from "@paid-ai/paid-node";
2
3
const client = new PaidClient({ token: "YOUR_PAID_API_KEY" });
4
5
const checkout = await client.checkouts.createCheckout({
6
  products: [{ id: "prod_abc123" }],
7
  externalCustomerId: currentUser.id, // your internal user/customer identifier
8
  successUrl: "https://example.com/success?checkout_id={CHECKOUT_ID}",
9
});
10
11
// Redirect your customer to this URL
12
redirect(checkout.body.url);

The {CHECKOUT_ID} placeholder in successUrl is automatically replaced with the checkout’s display ID (e.g. chk_abc123), so you can retrieve the result when the customer returns.

Handling the return

After payment, verify the checkout before provisioning access. Check that the status is completed and that externalCustomerId matches the currently authenticated user — this prevents one user from using another’s checkout ID to gain unauthorised access.

1
const checkoutId = req.query.checkout_id;
2
const checkout = await client.checkouts.getCheckout(checkoutId);
3
4
if (
5
  checkout.body.status === "completed" &&
6
  checkout.body.externalCustomerId === currentUser.id
7
) {
8
  await provisionUserAccess(currentUser.id);
9
} else {
10
  showErrorMessage();
11
}

Identifying the customer

There are three ways that customers become associated with a checkout.

externalCustomerId (recommended for most integrations)

Pass your own user identifier — a database ID, UUID, or email. On the first checkout for a given ID, Paid creates the customer automatically. On subsequent checkouts with the same ID, Paid resolves to the existing customer, so upgrades and plan changes work seamlessly without any extra setup.

1
const checkout = await client.checkouts.createCheckout({
2
  products: [{ id: "prod_abc123" }],
3
  externalCustomerId: currentUser.id,
4
  successUrl: "https://example.com/success",
5
});

customerId

If you’ve already created a customer in Paid — for example, via the Customers API or the dashboard — you can reference them directly by their Paid customer ID (cus_...).

1
const checkout = await client.checkouts.createCheckout({
2
  products: [{ id: "prod_abc123" }],
3
  customerId: "cus_xyz789",
4
  successUrl: "https://example.com/success",
5
});

Only one of customerId or externalCustomerId may be provided.

Anonymous

If you don’t have a customer yet — for example, on a public pricing page — omit both. The checkout page will collect the customer’s name and email, and Paid creates the customer record on completion.

1
const checkout = await client.checkouts.createCheckout({
2
  products: [{ id: "prod_abc123" }],
3
  successUrl: "https://example.com/welcome",
4
});

Multiple products

You can pass several products in a single session. If a product has plan tiers, the customer picks one during checkout. If it doesn’t, it’s shown directly with its base pricing.

1
const checkout = await client.checkouts.createCheckout({
2
  products: [
3
    { id: "prod_platform" },
4
    { id: "prod_addon_storage" },
5
  ],
6
  successUrl: "https://example.com/success",
7
});

Automatic upgrades

If the externalCustomerId already has an active order for the product, Paid automatically handles the upgrade with proration. No need for separate upgrade logic — the same API call works for both new purchases and plan changes.

1
// Works for both new customers and upgrades
2
const checkout = await client.checkouts.createCheckout({
3
  products: [{ id: "prod_abc123" }],
4
  externalCustomerId: currentUser.id,
5
  successUrl: "https://example.com/success",
6
});

Expiration

By default, checkout sessions expire after 24 hours. You can override this by setting expiresAt to an ISO 8601 timestamp.

1
const checkout = await client.checkouts.createCheckout({
2
  products: [{ id: "prod_abc123" }],
3
  successUrl: "https://example.com/welcome",
4
  expiresAt: "2026-04-01T00:00:00.000Z",
5
});

Metadata

You can attach arbitrary key-value metadata to a checkout session for your own tracking. This data is returned on the checkout object but is never shown to the customer.

1
const checkout = await client.checkouts.createCheckout({
2
  products: [{ id: "prod_abc123" }],
3
  successUrl: "https://example.com/welcome",
4
  metadata: { campaign: "spring_launch", referrer: "pricing_page" },
5
});

Settings

Currency

Lock the checkout to a specific currency with currency. If omitted, the customer can pay in any currency supported by the selected plan.

1
const checkout = await client.checkouts.createCheckout({
2
  products: [{ id: "prod_abc123" }],
3
  successUrl: "https://example.com/success",
4
  currency: "GBP", // customer will only be able to pay in GBP
5
});

Single use

By default, checkout sessions are single-use — the link is archived once a session has been started. Set singleUse: false for a reusable link, for example on a public pricing page.

1
const checkout = await client.checkouts.createCheckout({
2
  products: [{ id: "prod_abc123" }],
3
  successUrl: "https://example.com/success",
4
  singleUse: false,
5
});

Collecting customer information

By default, Paid collects the customer’s billing address (required for tax calculation). You can also request a phone number.

1
const checkout = await client.checkouts.createCheckout({
2
  products: [{ id: "prod_abc123" }],
3
  successUrl: "https://example.com/success",
4
  collectAddress: true,  // default — required for tax
5
  collectPhone: true,    // optional — off by default
6
});