Customers

Create, find, update, deactivate, and map Cipay customers from your backend.

A Cipay customer should map to one authenticated user in your application. Keep this mapping on your server; browser input must never decide which customer owns a request.

Create a customer

Create the customer after your application user exists. externalId is your stable application identifier for search and reconciliation.

import { createIdempotencyKey } from "@cipay/client-sdk/api";

const customer = await cipay.customers.create(
  {
    email: applicationUser.email,
    name: applicationUser.name,
    locale: "en",
    externalId: applicationUser.id,
  },
  {
    // Reuse this key only if this exact creation request is retried.
    idempotencyKey: createIdempotencyKey("customer"),
  },
);

Store the customer mapping

Persist the returned Cipay ID in your own user record. This is application storage, not another Cipay API call.

await users.update(applicationUser.id, {
  cipayCustomerId: customer.id,
});

customer.id is the authoritative value your resolveCustomer callback returns for authenticated account requests.

Search customers

customers.list returns { items, nextCursor }. Every item is a customer summary you can render immediately; retrieve a detail only when you need the current full record.

const page = await cipay.customers.list({
  query: "buyer@example.test",
  externalId: "user_42",
  subscription: "active",
  pageSize: 25,
});

console.info({
  returned: page.items.length,
  hasNextPage: page.nextCursor !== null,
});

To request the next page, send the returned cursor with the same filters.

if (page.nextCursor) {
  const nextPage = await cipay.customers.list({
    externalId: "user_42",
    subscription: "active",
    pageSize: 25,
    cursor: page.nextCursor,
  });
}

Filters also include payment state and createdFrom/createdTo ISO timestamps. See the customer list reference for the complete query and response schemas.

Edit a customer

Use customers.edit for profile fields. It does not change lifecycle status.

await cipay.customers.edit(
  customer.id,
  { name: "Updated Buyer", locale: "ar" },
  { idempotencyKey: createIdempotencyKey("customer-edit") },
);

Deactivate a customer

Deactivation preserves historical orders and subscriptions while preventing the customer from being treated as active.

await cipay.customers.deactivate(customer.id, {
  idempotencyKey: createIdempotencyKey("customer-deactivate"),
});

Reactivate a customer

Reactivate only after your application has confirmed the account should be usable again.

await cipay.customers.reactivate(customer.id, {
  idempotencyKey: createIdempotencyKey("customer-reactivate"),
});

List a customer’s subscriptions

const subscriptions = await cipay.customers.subscriptions(customer.id, {
  pageSize: 20,
});

console.info({
  customerId: customer.id,
  returned: subscriptions.items.length,
  hasNextPage: subscriptions.nextCursor !== null,
});

The response contains subscription summaries and a cursor. Inspect the complete response schema, then use the subscriptions guide for safe lifecycle mutations.

List a customer’s orders

const orders = await cipay.customers.orders(customer.id, {
  pageSize: 20,
});

console.info({
  customerId: customer.id,
  returned: orders.items.length,
  hasNextPage: orders.nextCursor !== null,
});

The customer orders reference documents every returned field and cursor behavior.