Quickstart
Get your first real call working with the SUQO TypeScript SDK.
1. Install
npm install @suqo/[email protected]2. Get a sandbox key
Grab a sandbox API key (su_test_key_...) from your seller dashboard. The key's prefix tells the SDK which environment to talk to — there's nothing else to configure.
3. Make your first call
import { SuqoClient } from "@suqo/sdk";
const suqo = new SuqoClient({ apiKey: process.env.SUQO_API_KEY! });
const page = await suqo.products.list();
console.log(page.results);A full end-to-end flow
A real integration is rarely one isolated call. Here's the shape of a complete flow — pick a product, then open a checkout session for it. This part is a one-off script, the same shape as step 3 above:
import { SuqoClient } from "@suqo/sdk";
const suqo = new SuqoClient({ apiKey: process.env.SUQO_API_KEY! });
// 1. List products, pick a billing period to charge.
const products = await suqo.products.list();
const billingPeriod = products.results[0]?.plan[0]?.billingPeriods[0];
// 2. Open a checkout session. No customerId, so the buyer enters their own details at
// checkout. checkoutUrl is where the buyer pays, not proof they did.
const session = await suqo.checkoutSessions.create({
returnUrl: "https://your-app.example/return",
items: [{ pbpId: billingPeriod!.pbpId }],
});
console.log(`Send the buyer to ${session.checkoutUrl}`);
// Save session.publicId with your order — the webhook below is matched back on it.checkoutUrl is not proof of payment. You learn the real outcome from a webhook, not from this response — which lives in your server as a persistent route, not this script:
import express from "express";
import { SuqoClient, type WebhookEvent } from "@suqo/sdk";
const app = express();
const suqo = new SuqoClient({ apiKey: process.env.SUQO_API_KEY! });
// Mount express.raw() on this route specifically — see Handle webhooks for why.
app.post("/hooks/suqo", express.raw({ type: "application/json" }), (req, res) => {
const ok = suqo.webhooks.verify({
rawBody: req.body,
signature: req.header("X-SUQO-Signature")!,
timestamp: req.header("X-SUQO-Timestamp")!,
secret: process.env.SUQO_WEBHOOK_SECRET!,
});
if (!ok) return res.sendStatus(400);
const event = JSON.parse(req.body.toString()) as WebhookEvent;
if (event.event === "checkout.succeeded") {
// event.session_id is the session.publicId you saved — mark that order paid
}
res.sendStatus(200); // ack fast; do the real work async
});Get the signing secret for SUQO_WEBHOOK_SECRET with suqo.webhooks.retrieveSecret(), and register the route with suqo.webhooks.create() — see Handle webhooks. For items, customers and rate limits, see Collect payments.