API Reference

Customers

Customer objects allow you to create and manage fundamental customer information, which is essential for creating subscriptions and one-time payments. This resource stores details such as contact information, billing addresses, and payment history.
This reference guide provides detailed information on all available API endpoints for the Customer resource. For a practical guide on integrating customer management into your application, see Checkout Sessions.
The Customer Object#A Customer object contains all the relevant information about one of your customers. The TCustomerExpanded type, returned by most endpoints, includes additional linked resources.
Attribute
Type
Description
id
string
Unique identifier for the customer object.
livemode
boolean
Indicates if the object exists in live mode (true) or test mode (false).
did
string
The customer's Decentralized Identifier (DID).
description
string
An arbitrary string that you can attach to a customer object.
name
string
The customer's full name or business name.
email
string
The customer's email address.
phone
string
The customer's phone number.
address
object
The customer's billing address. See structure below.
shipping
object
Shipping information for the customer. See structure below.
balance
string
Current balance, if any, that will be applied to the next invoice. A negative balance is a credit, and a positive balance is a debit.
token_balance
object
A record of token balances for different currencies.
delinquent
boolean
Whether the customer has an overdue payment.
metadata
object
A set of key-value pairs that you can attach to an object.
invoice_prefix
string
The prefix for the customer's invoices.
created_at
Date
Timestamp of when the object was created.
Address Object
Attribute
Type
Description
city
string
City, district, suburb, town, or village.
country
string
Two-letter country code (ISO 3166-1 alpha-2).
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.
state
string
State, county, province, or region.
Shipping Object
Attribute
Type
Description
address
object
The shipping address, following the Address Object structure.
name
string
The name of the recipient.
phone
string
The phone number of the recipient.
Retrieve a Customer#Retrieves the details of an existing customer. You need to provide the customer's unique id or did.
Parameters
Name
Type
Description
id
string
The unique identifier or DID of the customer to retrieve.
Returns
Returns a TCustomerExpanded object if a valid identifier was provided. Otherwise, this call returns an error.
async function retrieveCustomer(customerId) {
  try {
    const customer = await payment.customers.retrieve(customerId);
    console.log(customer);
  } catch (error) {
    console.error('Error retrieving customer:', error.message);
  }
}

// Example usage with a customer ID
retrieveCustomer('cus_xxxxxxxxxxxxxx');Example Response
{
  "id": "cus_xxxxxxxxxxxxxx",
  "livemode": false,
  "did": "did:abt:z123...",
  "description": "Test Customer",
  "name": "John Doe",
  "email": "john.doe@example.com",
  "phone": "+15551234567",
  "address": {
    "city": "Seattle",
    "country": "US",
    "line1": "123 Main St",
    "postal_code": "98101",
    "state": "WA"
  },
  "shipping": null,
  "balance": "0",
  "token_balance": {},
  "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 the Customer object attributes for available fields like name, email, description, etc.
Returns
Returns the updated TCustomer object.
async function updateCustomer(customerId) {
  try {
    const customer = await payment.customers.update(customerId, {
      description: 'Updated customer description',
      metadata: {
        order_id: '6735'
      }
    });
    console.log('Customer updated:', customer);
  } catch (error) {
    console.error('Error updating customer:', error.message);
  }
}

updateCustomer('cus_xxxxxxxxxxxxxx');Example Response
{
  "id": "cus_xxxxxxxxxxxxxx",
  "description": "Updated customer description",
  "email": "john.doe@example.com",
  "name": "John Doe",
  "metadata": {
    "order_id": "6735"
  }
}List all Customers#Returns a paginated list of your customers. The customers are returned sorted by creation date, with the most recent customers appearing first.
Parameters
Name
Type
Description
did
string
Optional. A DID to filter the customer list.
page
number
Optional. The page number for pagination.
pageSize
number
Optional. The number of items per page. Defaults to 20.
order
string or string[]
Optional. The order to sort the results by. Example: 'created_at:DESC'.
starting_after
string
Optional. A cursor for use in pagination. starting_after is an object ID that defines your place in the list.
ending_before
string
Optional. A cursor for use in pagination. ending_before is an object ID that defines your place in the list.
Returns
Returns a Paginated<TCustomerExpanded> object containing a list of customers.
async function listCustomers() {
  try {
    const customers = await payment.customers.list({ pageSize: 5 });
    console.log(`Found ${customers.count} customers.`);
    customers.list.forEach(customer => {
      console.log(`- ${customer.name} (ID: ${customer.id})`);
    });
  } catch (error) {
    console.error('Error listing customers:', error.message);
  }
}

listCustomers();Example Response
{
  "count": 50,
  "list": [
    {
      "id": "cus_xxxxxxxxxxxxxx",
      "name": "John Doe",
      "email": "john.doe@example.com",
      "created_at": "2023-10-27T10:00:00.000Z"
    },
    {
      "id": "cus_yyyyyyyyyyyyyy",
      "name": "Jane Smith",
      "email": "jane.smith@example.com",
      "created_at": "2023-10-26T12:00:00.000Z"
    }
  ]
}Search Customers#Returns a paginated list of customers that match a search query. This is useful for implementing customer search functionality in your application.
Parameters
Name
Type
Description
query
string
The search query string. The API will search across fields like name, email, and description.
page
number
Optional. The page number for pagination.
pageSize
number
Optional. The number of items per page. Defaults to 20.
Returns
Returns a Paginated<TCustomerExpanded> object containing a list of customers that match the search query.
async function searchCustomers(searchTerm) {
  try {
    const results = await payment.customers.search({ query: searchTerm });
    console.log(`Search results for "${searchTerm}":`);
    results.list.forEach(customer => {
      console.log(`- ${customer.name} (ID: ${customer.id})`);
    });
  } catch (error) {
    console.error('Error searching customers:', error.message);
  }
}

searchCustomers('john');Retrieve Current Customer#Retrieves the details of the currently authenticated customer based on the API key or session.
Parameters
None.
Returns
Returns the TCustomerExpanded object for the authenticated customer.
async function getCurrentCustomer() {
  try {
    const me = await payment.customers.me();
    console.log('Current customer:', me.name);
  } catch (error) {
    console.error('Error retrieving current customer:', error.message);
  }
}

getCurrentCustomer();Retrieve Overdue Invoices#Retrieves a list of all overdue invoices for a specific customer.
Parameters
Name
Type
Description
id
string
The identifier of the customer.
Returns
An object containing the customer details, a list of their overdue invoices, and a summary of the overdue amounts grouped by currency and payment method.
async function getOverdueInvoices(customerId) {
  try {
    const overdueData = await payment.customers.overdueInvoices(customerId);
    console.log(`Overdue invoices for ${overdueData.customer.name}:`);
    overdueData.invoices.forEach(invoice => {
      console.log(`- Invoice ${invoice.id}, Amount Due: ${invoice.amount_due}`);
    });
    console.log('Summary:', overdueData.summary);
  } catch (error) {
    console.error('Error retrieving overdue invoices:', error.message);
  }
}

getOverdueInvoices('cus_xxxxxxxxxxxxxx');Example Response
{
  "customer": {
    "id": "cus_xxxxxxxxxxxxxx",
    "name": "John Doe",
    "email": "john.doe@example.com"
  },
  "invoices": [
    {
      "id": "in_123...",
      "amount_due": "5000",
      "currency_id": "usd_mainnet",
      "due_date": 1672531199
    }
  ],
  "summary": {
    "usd_mainnet": {
      "amount": "5000",
      "currency": "usd_mainnet",
      "method": "stripe"
    }
  }
}
Now that you understand how to manage customers, you can proceed to learn about creating and managing their Subscriptions.

Attribute	Type	Description
`id`	`string`	Unique identifier for the customer object.
`livemode`	`boolean`	Indicates if the object exists in live mode (`true`) or test mode (`false`).
`did`	`string`	The customer's Decentralized Identifier (DID).
`description`	`string`	An arbitrary string that you can attach to a customer object.
`name`	`string`	The customer's full name or business name.
`email`	`string`	The customer's email address.
`phone`	`string`	The customer's phone number.
`address`	`object`	The customer's billing address. See structure below.
`shipping`	`object`	Shipping information for the customer. See structure below.
`balance`	`string`	Current balance, if any, that will be applied to the next invoice. A negative balance is a credit, and a positive balance is a debit.
`token_balance`	`object`	A record of token balances for different currencies.
`delinquent`	`boolean`	Whether the customer has an overdue payment.
`metadata`	`object`	A set of key-value pairs that you can attach to an object.
`invoice_prefix`	`string`	The prefix for the customer's invoices.
`created_at`	`Date`	Timestamp of when the object was created.

Attribute	Type	Description
`city`	`string`	City, district, suburb, town, or village.
`country`	`string`	Two-letter country code (ISO 3166-1 alpha-2).
`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.
`state`	`string`	State, county, province, or region.

Name	Type	Description
`id`	`string`	The identifier of the customer to be updated.
`data`	`object`	An object containing the fields to update. See the Customer object attributes for available fields like `name`, `email`, `description`, etc.

Name	Type	Description
`did`	`string`	Optional. A DID to filter the customer list.
`page`	`number`	Optional. The page number for pagination.
`pageSize`	`number`	Optional. The number of items per page. Defaults to 20.
`order`	`string` or `string[]`	Optional. The order to sort the results by. Example: `'created_at:DESC'`.
`starting_after`	`string`	Optional. A cursor for use in pagination. `starting_after` is an object ID that defines your place in the list.
`ending_before`	`string`	Optional. A cursor for use in pagination. `ending_before` is an object ID that defines your place in the list.

Name	Type	Description
`query`	`string`	The search query string. The API will search across fields like `name`, `email`, and `description`.
`page`	`number`	Optional. The page number for pagination.
`pageSize`	`number`	Optional. The number of items per page. Defaults to 20.

Overview

Get Started

Core Concepts

Usage Guides

API Reference

TypeScript Support

Customers

The Customer Object#

Retrieve a Customer#

Update a Customer#

List all Customers#

Search Customers#

Retrieve Current Customer#

Retrieve Overdue Invoices#

API Reference

Products

Attribute	Type	Description
`address`	`object`	The shipping address, following the Address Object structure.
`name`	`string`	The name of the recipient.
`phone`	`string`	The phone number of the recipient.