Collect payments
Open checkout sessions — the recommended way to collect payment — with the SUQO TypeScript SDK.
A checkout session charges one to ten items in a single checkout: you open it, send the buyer to the checkoutUrl it returns, SUQO runs the whole payment flow, and you learn the outcome from a webhook. It's the recommended way to collect payment, and replaces subscriptions.create(), which stays supported for integrations already built on it.
subscriptions.create().Opening one
const session = await suqo.checkoutSessions.create({
returnUrl: "https://your-app.example/orders/1234",
customerId: "cus_1ce18d624", // optional — see below
items: [
{ pbpId: billingPeriod.pbpId }, // a catalogue item, from products.list()
{ name: "Onboarding setup", amount: "2500.00", intervalType: "one_time", intervalCount: 0 },
],
});
session.publicId; // "cks_…" — also the session_id on the checkout webhooks
session.checkoutUrl; // send the buyer here
session.expiresAt; // when the URL stops working — about 30 minutes outreturnUrl. Learn the real outcome from checkout.succeeded/checkout.failed (see Handle webhooks), matched back to this session by session_id, which is the publicId above.The session stops working at expiresAt, so open a fresh one rather than caching it.
Items
Each element of items is one of two shapes — never a mix within one item:
| Shape | Fields | Charges |
|---|---|---|
CatalogueItemInput | pbpId | An existing billing period, at its catalogue price |
PartnerPricedItemInput | name, amount, intervalType, intervalCount | A price you set, with no billing period behind it |
amountis a decimal string (e.g."2500.00"), never anumber, and it must already include any discount — SUQO charges exactly what you send.intervalTypeisday,week,month,yearorone_time.intervalCountmultiplies it (1withmonthbills monthly): 1–1095 forday, 1–156 forweek, 1–36 formonth, 1–3 foryear, and0forone_time.- One to ten items. Fewer or more is a
ValidationError. - One item per product — the last one wins, silently. Two items resolving to the same product (e.g. two billing periods of one product) keep only the last, with no error. Collapse that choice in your own cart first.
- Prices are snapshotted when the session opens, so editing a plan afterwards can't change what the buyer was shown.
customerId
customerId | What the buyer sees |
|---|---|
| Sent | Goes straight to payment. Their details are already known and can't be edited at checkout — fix a typo with customers.update() and open a new session. |
| Omitted | Fills in their full name, email, phone and address at checkout. |
Record a buyer with customers.create() and pass the id it returns.
Rate limit
This is the API's one rate-limited endpoint: 20 sessions a minute per account. Past that it throws RateLimitError, with retryAfter set to the wait the API named, in milliseconds. Like every write, it's never retried automatically — catch it and retry yourself:
import { RateLimitError } from "@suqo/sdk";
try {
await suqo.checkoutSessions.create({ returnUrl, items });
} catch (err) {
if (err instanceof RateLimitError) {
await new Promise((resolve) => setTimeout(resolve, err.retryAfter ?? 60_000));
// …then retry, or tell the buyer to try again shortly
} else {
throw err;
}
}Open a session when the buyer commits to paying, not when they load a page — that keeps a busy catalogue well inside the limit.
Reading one back
const open = await suqo.checkoutSessions.retrieve("cks_3n9k2xQ7m");
open.lineItems; // CheckoutLineItem[]Only an open session can be read. Once it's paid or past expiresAt — or the id is unknown or another account's — retrieve() throws NotFoundError. The error's rawBody carries the session's return_url when it existed.
Shape
interface CheckoutSession {
publicId: string;
lineItems: CheckoutLineItem[];
customerId: string | null; // null when the buyer enters their own details
sellerDetails: CheckoutSeller;
returnUrl: string;
expiresAt: string; // kept as sent — may carry a +05:45 offset
completedAt: string | null;
isExpired: boolean;
sessionType: "subscription" | "billing" | string | null; // null if the API doesn't send it
}
interface CheckoutLineItem {
name: string; // the product name, or the name you sent
amount: string; // decimal string
pbpId: string | null; // null for a partner-priced item
currency: string;
vatType: "inclusive" | "exclusive" | null;
vatPercentage: string | null; // decimal string
discountAmount: string | null; // decimal string
intervalType: string; // day | week | month | year | one_time
intervalCount: number;
displayLabel: string; // e.g. "Monthly", "Every 2 months"
currentPeriodEnd: string | null;
extendsTo: string | null; // YYYY-MM-DD
nextPaymentDue: string | null; // YYYY-MM-DD
imageUrls?: string[]; // catalogue items only
planName?: string | null; // partner-priced items only
subscriptionId?: string; // the subscription this line pays for, once it has one (2.1.0+)
}
interface CheckoutSeller {
id: string;
phone: string; // the seller's own number — personal data, don't log it
businessLogo: string | null;
businessName: string;
}imageUrls appears only on catalogue items and planName only on partner-priced ones — each is absent, not null, on the other kind. subscriptionId (new in 2.1.0) names the subscription the line pays for. A renewal session always has it; an open new purchase gets its subscription only once the buyer pays, so it can be absent until then. sessionType doesn't tell a renewal from a new purchase: it has come back "subscription" for both. Every other nullable field comes back null, never undefined.
Retries
create() is a write, so it's never retried automatically — a retried timeout could open a second session. retrieve() is a read and retries on NetworkError, 429 and 5xx like every read. See Handle errors.