Skip to main content

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.

AttributeTypeDescription
idstringUnique identifier for the customer object, starting with cus_.
didstringThe customer's Decentralized Identifier (DID).
livemodebooleantrue if the object exists in live mode, or false if it exists in test mode.
namestringThe customer's full name.
emailstringThe customer's primary email address.
phonestringThe customer's primary phone number.
addressobjectThe customer's billing address. See the Address object properties below.
balancestringThe current credit balance of the customer.
delinquentbooleanWhether the customer has an overdue payment.
metadataobjectA set of key-value pairs that you can attach to an object.
created_atstringThe timestamp of when the customer was created.
updated_atstringThe timestamp of the last update to the customer object.

Address Object Properties

AttributeTypeDescription
countrystringTwo-letter country code (ISO 3166-1 alpha-2).
statestringState, province, prefecture, or region.
citystringCity, district, suburb, town, or village.
line1stringAddress line 1 (e.g., street, PO Box, or company name).
line2stringAddress line 2 (e.g., apartment, suite, unit, or building).
postal_codestringZIP or postal code.

Retrieve a Customer

Retrieves the details of an existing customer by providing their unique ID or DID.

Parameters

NameTypeDescription
idstringThe 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

javascript
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

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

NameTypeDescription
idstringThe identifier of the customer to be updated.
dataobjectAn object containing the fields to update. See details below.

Data Object Properties

AttributeTypeDescription
namestringThe customer's full name.
emailstringThe customer's email address.
phonestringThe customer's phone number.
addressobjectThe customer's billing address. Follows the Address object structure.
metadataobjectA set of key-value pairs to store with the customer.

Returns

Returns the updated TCustomer object.

Example

Update a Customer

javascript
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

NameTypeDescription
paramsobjectAn object containing pagination and filtering parameters.

Params Object Properties

AttributeTypeDescription
didstringOptional. Filter the list to customers with a specific DID.
pagenumberOptional. The page number to retrieve. Defaults to 1.
pageSizenumberOptional. 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

javascript
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

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

NameTypeDescription
paramsobjectAn object containing search and pagination parameters.

Params Object Properties

AttributeTypeDescription
querystringThe search string.
pagenumberOptional. The page number to retrieve. Defaults to 1.
pageSizenumberOptional. 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

javascript
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

NameTypeDescription
idstringThe 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

javascript
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

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