Customer objects allow you to create and manage the customers your business serves. They store essential information such as contact details, addresses, and billing history, which are fundamental for creating subscriptions and processing payments.
The Customer Object
A Customer object represents a unique customer in your system.
| Attribute | Type | Description |
|---|---|---|
id | string | Unique identifier for the customer object, starting with cus_. |
did | string | The customer's Decentralized Identifier (DID). |
livemode | boolean | true if the object exists in live mode, or false if it exists in test mode. |
name | string | The customer's full name. |
email | string | The customer's primary email address. |
phone | string | The customer's primary phone number. |
address | object | The customer's billing address. See the Address object properties below. |
balance | string | The current credit balance of the customer. |
delinquent | boolean | Whether the customer has an overdue payment. |
metadata | object | A set of key-value pairs that you can attach to an object. |
created_at | string | The timestamp of when the customer was created. |
updated_at | string | The timestamp of the last update to the customer object. |
Address Object Properties
| Attribute | Type | Description |
|---|---|---|
country | string | Two-letter country code (ISO 3166-1 alpha-2). |
state | string | State, province, prefecture, or region. |
city | string | City, district, suburb, town, or village. |
line1 | string | Address line 1 (e.g., street, PO Box, or company name). |
line2 | string | Address line 2 (e.g., apartment, suite, unit, or building). |
postal_code | string | ZIP or postal code. |
Retrieve a Customer
Retrieves the details of an existing customer by providing their unique ID or DID.
Parameters
| Name | Type | Description |
|---|---|---|
id | string | The identifier of the customer to be retrieved (cus_... or a DID). |
Returns
Returns a TCustomerExpanded object if a customer with the given ID exists.
Example
Retrieve a Customer
async function retrieveCustomer(customerId) {
try {
const customer = await payment.customers.retrieve(customerId);
console.log('Retrieved customer:', customer);
return customer;
} catch (error) {
console.error('Error retrieving customer:', error.message);
}
}
// Example usage with a customer ID
retrieveCustomer('cus_xxxxxxxxxxxxxxxx');Example Response
Example Customer Object
{
"id": "cus_xxxxxxxxxxxxxxxx",
"did": "zNK...",
"livemode": true,
"name": "John Doe",
"email": "john.doe@example.com",
"phone": "+15551234567",
"address": {
"country": "US",
"state": "CA",
"city": "San Francisco",
"line1": "123 Main Street",
"line2": "Apt 4B",
"postal_code": "94105"
},
"balance": "100.00",
"delinquent": false,
"metadata": {},
"created_at": "2023-10-27T10:00:00.000Z",
"updated_at": "2023-10-27T10:00:00.000Z"
}Update a Customer
Updates the specified customer by setting the values of the parameters passed. Any parameters not provided will be left unchanged.
Parameters
| Name | Type | Description |
|---|---|---|
id | string | The identifier of the customer to be updated. |
data | object | An object containing the fields to update. See details below. |
Data Object Properties
| Attribute | Type | Description |
|---|---|---|
name | string | The customer's full name. |
email | string | The customer's email address. |
phone | string | The customer's phone number. |
address | object | The customer's billing address. Follows the Address object structure. |
metadata | object | A set of key-value pairs to store with the customer. |
Returns
Returns the updated TCustomer object.
Example
Update a Customer
async function updateCustomerDetails(customerId) {
try {
const updatedCustomer = await payment.customers.update(customerId, {
email: 'john.new.doe@example.com',
metadata: {
internal_id: 'user-456'
}
});
console.log('Customer updated successfully:', updatedCustomer);
return updatedCustomer;
} catch (error) {
console.error('Error updating customer:', error.message);
}
}
updateCustomerDetails('cus_xxxxxxxxxxxxxxxx');List all Customers
Returns a paginated list of your customers.
Parameters
| Name | Type | Description |
|---|---|---|
params | object | An object containing pagination and filtering parameters. |
Params Object Properties
| Attribute | Type | Description |
|---|---|---|
did | string | Optional. Filter the list to customers with a specific DID. |
page | number | Optional. The page number to retrieve. Defaults to 1. |
pageSize | number | Optional. The number of customers to retrieve per page. Defaults to 20. |
Returns
Returns a paginated object containing a list of TCustomerExpanded objects and pagination details.
Example
List Customers
async function listCustomers() {
try {
const response = await payment.customers.list({ pageSize: 5 });
console.log(`Total customers: ${response.count}`);
console.log('First page of customers:', response.list);
return response;
} catch (error) {
console.error('Error listing customers:', error.message);
}
}
listCustomers();Example Response
Paginated Customer List
{
"count": 50,
"list": [
{
"id": "cus_xxxxxxxxxxxxxxxx",
"did": "zNK...",
"name": "John Doe",
"email": "john.doe@example.com",
// ... other customer fields
}
// ... more customer objects
],
"paging": {
"page": 1,
"pageSize": 5
}
}Search Customers
Returns a paginated list of customers that match a search query. The search is performed on fields like name, email, and DID.
Parameters
| Name | Type | Description |
|---|---|---|
params | object | An object containing search and pagination parameters. |
Params Object Properties
| Attribute | Type | Description |
|---|---|---|
query | string | The search string. |
page | number | Optional. The page number to retrieve. Defaults to 1. |
pageSize | number | Optional. The number of customers to retrieve per page. Defaults to 20. |
Returns
Returns a paginated object containing a list of TCustomerExpanded objects that match the search query.
Example
Search for Customers
async function searchForCustomer(query) {
try {
const results = await payment.customers.search({ query: query });
console.log(`Found ${results.count} customer(s) matching '${query}':`, results.list);
return results;
} catch (error) {
console.error('Error searching for customers:', error.message);
}
}
searchForCustomer('john.doe');Retrieve Overdue Invoices
Retrieves a list of uncollectible invoices for a specific customer, along with a summary of the total amounts due, grouped by currency.
Parameters
| Name | Type | Description |
|---|---|---|
id | string | The identifier of the customer. |
Returns
An object containing the customer, a list of their overdue invoices, and a summary of the amounts due.
Example
Get Overdue Invoices
async function getOverdueInvoices(customerId) {
try {
const overdueData = await payment.customers.overdueInvoices(customerId);
console.log('Overdue invoices data:', overdueData);
return overdueData;
} catch (error) {
console.error('Error retrieving overdue invoices:', error.message);
}
}
getOverdueInvoices('cus_xxxxxxxxxxxxxxxx');Example Response
Overdue Invoices Response
{
"customer": {
"id": "cus_xxxxxxxxxxxxxxxx",
// ... customer details
},
"invoices": [
{
"id": "in_yyyyyyyyyyyyyyyy",
"status": "uncollectible",
"amount_remaining": "2500",
"currency_id": "curr_zzzzzzzzzzzzzzzz",
// ... other invoice details
}
],
"summary": {
"curr_zzzzzzzzzzzzzzzz": {
"amount": "2500",
"currency": {
// ... payment currency details
},
"method": {
// ... payment method details
}
}
}
}