SUQODocs
User GuideAPI ReferenceSDKs
TypeScript SDK v2.0.0. This version is frozen and no longer updated. Read the latest (2.1.0).

Customers

Listing, retrieving, creating and updating customers with the SUQO TypeScript SDK.

list(), retrieve(), create() and update(). There's no delete. A customer record is also created implicitly the first time someone subscribes, via subscriptions.create()'s customer field — create() is for recording one without opening a subscription.

A customer you record here can be passed to checkoutSessions.create() as customerId, which sends the buyer straight to payment without asking for their details again.

Listing

const page = await suqo.customers.list();
page.results; // Customer[]

Paginated like every other list endpoint — see Pagination.

Retrieving one

const customer = await suqo.customers.retrieve("cus_1ce18d624");

id is an opaque prefixed string (e.g. cus_1ce18d624) — like pbp_... on billing periods, not an integer and not a UUID.

Creating one

const customer = await suqo.customers.create({
  email: "[email protected]", // required
  phone: "9800000000", // optional
  fullName: "Ram Bahadur",
  address: "Kathmandu",
});
Changed in 2.0.0. email identifies the buyer and is required; phone is optional. In 1.x, phone was required. Pass email on every customers.create() call.
  • phone, if you send it, can't be changed later. It must be a Nepali mobile number (10 digits starting with 96, 97 or 98); a +977 country code, a leading 0, spaces and dashes are accepted and stripped.
  • If you already have a customer with that email or phone, create() updates that customer instead of making a second one, and returns it. That makes create() safe for you to retry — though the SDK never retries it automatically, like every write.
  • The name and address are your account's own copy of the buyer's details and aren't shared with other sellers.
  • Write vs. read names: you send phone/email, and they come back on the Customer as buyerPhone/buyerEmail.

Updating one

const updated = await suqo.customers.update("cus_1ce18d624", { fullName: "Ram Bahadur" });

Send only the fields you're changing — anything you leave out stays as it is. Pass "" to clear a field. The phone can't be changed, so it isn't an option here.

A validation problem (a bad phone or email) throws ValidationError with fieldErrors — see Handle errors.

Shape

interface Customer {
  id: string;
  buyerPhone: string | null;
  buyerEmail: string | null;
  fullName: string | null;
  address: string | null;
  createdAt: string;
}

Every field except id/createdAt can be null — a customer record doesn't guarantee it has a phone, email, or address on file.

This is a genuinely different shape from the customer object embedded on a Subscription (see Subscriptions) — that one uses phone/fullName/email with no buyer prefix, plus nested billing/shipping. They're related concepts (both describe a buyer) but not the same type, and the SDK never conflates them.

On this page