Customers

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#

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#

{
  "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#

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#

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#

{
  "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#

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#

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#

{
  "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
      }
    }
  }