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 — list a product, then create a subscription 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 subscribe to.
const products = await suqo.products.list();
const billingPeriod = products.results[0]?.plan[0]?.billingPeriods[0];
// 2. Create the subscription. It comes back in "pending_checkout" — checkoutUrl
// is where the buyer pays, not proof they did.
const subscription = await suqo.subscriptions.create({
pbpId: billingPeriod!.pbpId,
returnUrl: "https://your-app.example/return",
customer: { phone: "9800000001", fullName: "John Doe", email: "[email protected]", address: "Kathmandu" },
});checkoutUrl is not proof of payment. A newly created subscription is
pending_checkout until the buyer actually pays. 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 } from "@suqo/sdk";
const app = express();
const suqo = new SuqoClient({ apiKey: process.env.SUQO_API_KEY! });
// Mount express.raw() on this route specifically — see 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);
res.sendStatus(200); // ack fast; do the real work async
});