API Reference

Customers

Customer objects allow you to create and manage your customers. They store essential information such as contact details, addresses, and billing history, which can be used for creating subscriptions and one-time payments.
This document provides a detailed guide on how to interact with the Customer API resource.
The Customer Object#A Customer object contains detailed information about one of your customers.
Attribute
Type
Description
id
string
Unique identifier for the object, starting with cus_.
did
string
The Decentralized Identifier (DID) of the customer.
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. See the Address object properties below.
description
string
An arbitrary string that you can attach to a customer object.
balance
string
The current balance for the customer, in the smallest currency unit.
livemode
boolean
true if the object exists in live mode, or false if the object exists in test mode.
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.
The Address Object#Attribute
Type
Description
country
string
Two-letter country code (ISO 3166-1 alpha-2).
state
string
State, county, province, 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. You need to provide the unique customer identifier (id or did).
Parameters
Name
Type
Description
id
string
The unique identifier or DID of the customer to retrieve.
Returns
Returns a customer object if a valid identifier was provided. Throws an error otherwise.
Example
import payment from '@blocklet/payment-js';

async function retrieveCustomer(customerId) {
  try {
    const customer = await payment.customers.retrieve(customerId);
    console.log('Retrieved customer:', customer);
  } catch (error) {
    console.error('Error retrieving customer:', error.message);
  }
}

retrieveCustomer('cus_xxxxxxxxxxxxxxxx');Example Response
{
  "id": "cus_xxxxxxxxxxxxxxxx",
  "did": "zNK...",
  "name": "John Doe",
  "email": "john.doe@example.com",
  "phone": "+15551234567",
  "address": {
    "city": "Seattle",
    "country": "US",
    "line1": "123 Main St",
    "line2": "Apt 4B",
    "postal_code": "98101",
    "state": "WA"
  },
  "description": "Loyal customer since 2023",
  "balance": "0",
  "livemode": true,
  "metadata": {},
  "created_at": "2023-10-27T10:00:00.000Z",
  "updated_at": "2023-10-27T10:00:00.000Z"
}
List all Customers#Returns a paginated list of your customers.
Parameters
Name
Type
Description
page
number
Optional. The page number for pagination. Defaults to 1.
pageSize
number
Optional. The number of items per page. Defaults to 20.
did
string
Optional. Filter the list to a specific customer DID.
Returns
A paginated object containing a list of customer objects and paging information.
Example
import payment from '@blocklet/payment-js';

async function listCustomers() {
  try {
    const response = await payment.customers.list({ page: 1, pageSize: 5 });
    console.log(`Total customers: ${response.count}`);
    response.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_xxxxxxxxxxxxxxxx",
      "did": "zNK...",
      "name": "John Doe",
      "email": "john.doe@example.com",
      "livemode": true
    },
    {
      "id": "cus_yyyyyyyyyyyyyyyy",
      "did": "zM...",
      "name": "Jane Smith",
      "email": "jane.smith@example.com",
      "livemode": true
    }
  ],
  "paging": {
    "page": 1,
    "pageSize": 5
  }
}
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 update.
data
object
An object containing the fields to update. See details below.
data Object Properties
Name
Type
Description
name
string
Optional. The customer's full name.
email
string
Optional. The customer's email address.
phone
string
Optional. The customer's phone number.
address
object
Optional. The customer's billing address. See the Address Object section for details.
metadata
object
Optional. A set of key-value pairs to store with the customer.
Returns
Returns the updated customer object.
Example
import payment from '@blocklet/payment-js';

async function updateCustomer(customerId) {
  try {
    const updatedCustomer = await payment.customers.update(customerId, {
      email: 'john.doe.new@example.com',
      metadata: {
        'internal_id': '42'
      }
    });
    console.log('Customer updated:', updatedCustomer.id, updatedCustomer.email);
  } catch (error) {
    console.error('Error updating customer:', error.message);
  }
}

updateCustomer('cus_xxxxxxxxxxxxxxxx');Example Response
{
  "id": "cus_xxxxxxxxxxxxxxxx",
  "did": "zNK...",
  "name": "John Doe",
  "email": "john.doe.new@example.com",
  "metadata": {
    "internal_id": "42"
  },
  "updated_at": "2023-10-28T12:30:00.000Z"
}
Search for Customers#Returns a paginated list of customers that match a search query.
Parameters
Name
Type
Description
query
string
The search string to match against customer fields like name or email.
page
number
Optional. The page number for pagination. Defaults to 1.
pageSize
number
Optional. The number of items per page. Defaults to 20.
Returns
A paginated object containing a list of matching customer objects and paging information.
Example
import payment from '@blocklet/payment-js';

async function searchForCustomer(query) {
  try {
    const results = await payment.customers.search({ query: query });
    console.log(`Found ${results.count} customers matching "${query}":`);
    results.list.forEach(customer => {
      console.log(`- ${customer.name} (ID: ${customer.id})`);
    });
  } catch (error) {
    console.error('Error searching customers:', error.message);
  }
}

searchForCustomer('john.doe');Example Response
{
  "count": 1,
  "list": [
    {
      "id": "cus_xxxxxxxxxxxxxxxx",
      "did": "zNK...",
      "name": "John Doe",
      "email": "john.doe.new@example.com"
    }
  ],
  "paging": {
    "page": 1,
    "pageSize": 20
  }
}
List Overdue Invoices#Retrieves a list of uncollectible invoices for a specific customer. This is useful for identifying customers with payment issues.
Parameters
Name
Type
Description
id
string
The identifier of the customer.
Returns
An object containing the customer details, a list of overdue invoices, and a summary object that aggregates the total overdue amounts by currency and payment method.
Example
import payment from '@blocklet/payment-js';

async function getOverdueInvoices(customerId) {
  try {
    const result = await payment.customers.overdueInvoices(customerId);
    console.log('Customer:', result.customer.name);
    console.log('Total Overdue Invoices:', result.invoices.length);
    console.log('Overdue Summary:', result.summary);
  } catch (error) {
    console.error('Error fetching overdue invoices:', error.message);
  }
}

getOverdueInvoices('cus_xxxxxxxxxxxxxxxx');Example Response
{
  "summary": {
    "usd_xxxxxxxx": {
      "amount": "5000",
      "currency": {
        "id": "usd_xxxxxxxx",
        "name": "US Dollar"
      },
      "method": {
        "id": "card_xxxxxxxx",
        "type": "card"
      }
    }
  },
  "invoices": [
    {
      "id": "in_xxxxxxxxxxxxxxx1",
      "customer_id": "cus_xxxxxxxxxxxxxxxx",
      "status": "uncollectible",
      "amount_remaining": "2000",
      "currency_id": "usd_xxxxxxxx"
    },
    {
      "id": "in_xxxxxxxxxxxxxxx2",
      "customer_id": "cus_xxxxxxxxxxxxxxxx",
      "status": "uncollectible",
      "amount_remaining": "3000",
      "currency_id": "usd_xxxxxxxx"
    }
  ],
  "subscriptionCount": 2,
  "customer": {
    "id": "cus_xxxxxxxxxxxxxxxx",
    "name": "John Doe"
  }
}This guide covers the core functionalities for managing customers. For details on related resources, see the Subscriptions or Checkout Sessions documentation.

Overview

Getting Started

SDK Structure

Environments

Core Concepts

API Reference

Customers

The Customer Object#

The Address Object#

Retrieve a Customer#

List all Customers#

Update a Customer#

Search for Customers#

List Overdue Invoices#

Checkout Sessions

Products

Attribute	Type	Description
`id`	string	Unique identifier for the object, starting with `cus_`.
`did`	string	The Decentralized Identifier (DID) of the customer.
`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. See the Address object properties below.
`description`	string	An arbitrary string that you can attach to a customer object.
`balance`	string	The current balance for the customer, in the smallest currency unit.
`livemode`	boolean	`true` if the object exists in live mode, or `false` if the object exists in test mode.
`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.

Attribute	Type	Description
`country`	string	Two-letter country code (ISO 3166-1 alpha-2).
`state`	string	State, county, province, 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.

Name	Type	Description
`page`	number	Optional. The page number for pagination. Defaults to `1`.
`pageSize`	number	Optional. The number of items per page. Defaults to `20`.
`did`	string	Optional. Filter the list to a specific customer DID.

Name	Type	Description
`id`	string	The identifier of the customer to update.
`data`	object	An object containing the fields to update. See details below.

Name	Type	Description
`name`	string	Optional. The customer's full name.
`email`	string	Optional. The customer's email address.
`phone`	string	Optional. The customer's phone number.
`address`	object	Optional. The customer's billing address. See the Address Object section for details.
`metadata`	object	Optional. A set of key-value pairs to store with the customer.

Name	Type	Description
`query`	string	The search string to match against customer fields like `name` or `email`.
`page`	number	Optional. The page number for pagination. Defaults to `1`.
`pageSize`	number	Optional. The number of items per page. Defaults to `20`.