Customers
Customers — methods, parameters, and examples for @easylabs/node.
A customer is the buyer-side identity that owns payment instruments, orders, subscriptions, and wallets. Create one before charging via the standalone resource flow, or skip ahead and let checkout({ customer_creation: true }) create the customer + instrument inline.
Methods
createCustomer(customer)
POST /customer. Returns ApiResponse<CustomerData>.
const { data: customer } = await easy.createCustomer({
first_name: "Ada",
last_name: "Lovelace",
email: "ada@example.com",
phone: "+15555550101",
personal_address: {
line1: "1 Pioneer Way",
city: "Menlo Park",
region: "CA",
postal_code: "94025",
country: "USA",
},
tags: { signup_source: "web" },
});updateCustomer(customerId, partial)
PATCH /customer/:id. Accepts a Partial<CreateCustomer>.
await easy.updateCustomer(customer.id, { phone: "+15555550199" });getCustomer(customerId)
GET /customer/:id.
getCustomers(params?)
GET /customer. Standard PaginationParams (limit, offset, ids[]).
const { data: customers } = await easy.getCustomers({ limit: 50, offset: 0 });getCustomerPaymentInstruments(customerId)
GET /customer/:id/instruments. Returns the customer's stored cards and bank accounts.
getCustomerOrders(customerId, params?)
GET /customer/:id/orders.
getCustomerSubscriptions(customerId, params?)
GET /customer/:id/subscriptions. Adds an optional status?: SubscriptionStatus filter alongside pagination, and returns a Paginated<SubscriptionData> envelope ({ data, total, limit, offset }).
const page = await easy.getCustomerSubscriptions(customer.id, {
status: "ACTIVE",
limit: 25,
});
console.log(page.data.total, page.data.data.length);getCustomerWallets(customerId, params?)
GET /customer/:id/wallets. Connected crypto wallets.
Object shape
CustomerData mirrors the underlying entity record: top-level id, created_at, updated_at, tags (string-valued bag including company_id), entity (the full PII / merchant-onboarding record), identity_roles, and _links. Refer to the API reference for the canonical schema; the SDK re-exports the type as CustomerData from @easylabs/node.
Examples
Idempotent upsert by email
The API does not enforce email uniqueness — implement upsert in user code by listing first:
async function upsertCustomerByEmail(email: string, defaults: { first_name: string; last_name: string }) {
const all = await easy.getCustomers({ limit: 100 });
const existing = all.data.find((c) => c.entity.email === email);
if (existing) return existing;
const { data } = await easy.createCustomer({ ...defaults, email });
return data;
}Walk every order for a customer
async function ordersFor(customerId: string) {
const limit = 100;
let offset = 0;
const acc = [];
while (true) {
const { data } = await easy.getCustomerOrders(customerId, { limit, offset });
acc.push(...data);
if (data.length < limit) break;
offset += limit;
}
return acc;
}Tag-driven partial update
await easy.updateCustomer(customer.id, {
tags: { ...customer.tags, kyc_status: "verified" },
});