Browse the catalog
Browsing your product catalog with the SUQO TypeScript SDK.
Read-only — the only resource that works before your seller account completes KYC verification, since there's no seller action involved in just browsing your own catalog.
Listing products
const page = await suqo.products.list();
page.results; // Product[]list() is paginated — see Pagination for page/pageSize and .autoPaging(). It takes the same { page?, pageSize? } params every paginated resource does:
await suqo.products.list({ page: 2, pageSize: 50 });Finding a billing period to charge
A Product carries its plan[], and each Plan carries its billingPeriods[]. The pbpId on a billing period is what you pass to checkoutSessions.create() (or the legacy subscriptions.create()) — it's the one identifier that ties "what a buyer is browsing" to "what they pay for":
const product = page.results[0];
const billingPeriod = product?.plan[0]?.billingPeriods[0];
if (!billingPeriod) throw new Error("no billing period available");
await suqo.checkoutSessions.create({
returnUrl: "https://your-app.example/return",
items: [{ pbpId: billingPeriod.pbpId }],
});Check a billing period's intervalType before offering cancel or resume: one_time is a single purchase, and what it creates can't be cancelled, resumed, rescheduled or renewed (see One-time purchases).
Fields worth knowing about
vatcan benull— not every product has VAT configured. Inside it,vatType("inclusive"or"exclusive") andvatPercentagecan each benulltoo.price,vatPercentage,totalSubscribersare decimal-shaped values sent as strings on the wire (e.g."500.00") and kept as strings end to end — never coerced tonumber. Format or parse them yourself if you need arithmetic; the SDK won't silently round anything.description,termsAndConditions,featuresAndBenefits(and a plan'sdescription) can benull.typeis"simple"or"tiered";intervalTypeis"day","week","month","year"or"one_time". A value the API adds later passes through as a plain string rather than breaking your code.offerslists a billing period's discounts.discountAmountis a whole number of rupees (anumber, not a decimal string), and it's already applied topricewhile the offer is active — don't subtract it again.planand a plan'sbillingPeriodscan both come back empty — a product with no plans configured yet is spec-legal, not a bug in your integration.
| null, and offers is Offer[] rather than unknown[]. Handle null where you read them as plain strings.interface Product {
productId: string;
name: string;
description: string | null;
type: "simple" | "tiered";
isActive: boolean;
termsAndConditions: string | null;
featuresAndBenefits: string | null;
vat: ProductVat | null; // { isVatActive, vatType: "inclusive" | "exclusive" | null, vatPercentage: string | null }
productImage: ProductImage[]; // { image: string; imageOrder: number }
plan: Plan[];
totalSubscribers: string; // decimal string
createdAt: string;
updatedAt: string;
}
interface BillingPeriod {
pbpId: string;
intervalType: "day" | "week" | "month" | "year" | "one_time";
intervalCount: number;
label: string;
price: string; // decimal string, active offer already applied
currency: string;
isCurrent: boolean;
isLimited: boolean;
isArchived: boolean;
offers: Offer[];
}
interface Offer {
id: string;
discountAmount: number; // whole rupees — already applied to price
startsAt: string | null; // YYYY-MM-DD
validUntil: string | null; // YYYY-MM-DD
isActive: boolean;
}