API 参考

客户

客户对象允许您创建和管理客户的基本信息，这对于创建订阅和一次性付款至关重要。该资源存储了联系信息、账单地址和付款历史等详细信息。
本参考指南提供了客户资源所有可用 API 端点的详细信息。有关将客户管理集成到您的应用程序中的实用指南，请参阅 Checkout Sessions。
客户对象#一个 Customer 对象包含您某位客户的所有相关信息。大多数端点返回的 TCustomerExpanded 类型包含额外的关联资源。
属性
类型
描述
id
string
客户对象的唯一标识符。
livemode
boolean
指示对象是否存在于生产模式 (true) 或测试模式 (false)。
did
string
客户的去中心化身份标识（DID）。
description
string
您可以附加到客户对象的任意字符串。
name
string
客户的全名或企业名称。
email
string
客户的电子邮件地址。
phone
string
客户的电话号码。
address
object
客户的账单地址。请参阅下文的结构。
shipping
object
客户的配送信息。请参阅下文的结构。
balance
string
将应用于下一张发票的当前余额（如有）。负数余额表示贷方，正数余额表示借方。
token_balance
object
不同货币的代币余额记录。
delinquent
boolean
客户是否有逾期付款。
metadata
object
一组您可以附加到对象的键值对。
invoice_prefix
string
客户发票的前缀。
created_at
Date
对象创建时的时间戳。
地址对象
属性
类型
描述
city
string
城市、区、郊区、城镇或村庄。
country
string
两位字母的国家代码（ISO 3166-1 alpha-2）。
line1
string
地址行 1（例如，街道、邮政信箱或公司名称）。
line2
string
地址行 2（例如，公寓、套房、单元或建筑物）。
postal_code
string
邮政编码。
state
string
州、县、省或地区。
配送对象
属性
类型
描述
address
object
配送地址，遵循地址对象结构。
name
string
收件人的姓名。
phone
string
收件人的电话号码。
检索客户#检索现有客户的详细信息。您需要提供客户的唯一 id 或 did。
参数
名称
类型
描述
id
string
要检索的客户的唯一标识符或 DID。
返回
如果提供了有效的标识符，则返回一个 TCustomerExpanded 对象。否则，此调用将返回一个错误。
async function retrieveCustomer(customerId) {
  try {
    const customer = await payment.customers.retrieve(customerId);
    console.log(customer);
  } catch (error) {
    console.error('检索客户时出错：', error.message);
  }
}

// Example usage with a customer ID
retrieveCustomer('cus_xxxxxxxxxxxxxx');响应示例
{
  "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"
}更新客户#通过设置传入参数的值来更新指定的客户。任何未提供的参数都将保持不变。
参数
名称
类型
描述
id
string
要更新的客户的标识符。
data
object
一个包含要更新字段的对象。有关可用字段（如 name、email、description 等），请参阅客户对象的属性。
返回
返回更新后的 TCustomer 对象。
async function updateCustomer(customerId) {
  try {
    const customer = await payment.customers.update(customerId, {
      description: '更新后的客户描述',
      metadata: {
        order_id: '6735'
      }
    });
    console.log('客户已更新：', customer);
  } catch (error) {
    console.error('更新客户时出错：', error.message);
  }
}

updateCustomer('cus_xxxxxxxxxxxxxx');响应示例
{
  "id": "cus_xxxxxxxxxxxxxx",
  "description": "更新后的客户描述",
  "email": "john.doe@example.com",
  "name": "John Doe",
  "metadata": {
    "order_id": "6735"
  }
}列出所有客户#返回您的客户的分页列表。客户按创建日期排序，最新的客户最先显示。
参数
名称
类型
描述
did
string
可选。用于筛选客户列表的 DID。
page
number
可选。用于分页的页码。
pageSize
number
可选。每页的项目数。默认为 20。
order
string or string[]
可选。对结果进行排序的顺序。示例：'created_at:DESC'。
starting_after
string
可选。用于分页的游标。starting_after 是一个对象 ID，用于定义您在列表中的位置。
ending_before
string
可选。用于分页的游标。ending_before 是一个对象 ID，用于定义您在列表中的位置。
返回
返回一个包含客户列表的 Paginated<TCustomerExpanded> 对象。
async function listCustomers() {
  try {
    const customers = await payment.customers.list({ pageSize: 5 });
    console.log(`找到 ${customers.count} 位客户。`);
    customers.list.forEach(customer => {
      console.log(`- ${customer.name} (ID: ${customer.id})`);
    });
  } catch (error) {
    console.error('列出客户时出错：', error.message);
  }
}

listCustomers();响应示例
{
  "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"
    }
  ]
}搜索客户#返回与搜索查询匹配的客户的分页列表。这对于在您的应用程序中实现客户搜索功能非常有用。
参数
名称
类型
描述
query
string
搜索查询字符串。API 将在 name、email 和 description 等字段中进行搜索。
page
number
可选。用于分页的页码。
pageSize
number
可选。每页的项目数。默认为 20。
返回
返回一个 Paginated<TCustomerExpanded> 对象，其中包含与搜索查询匹配的客户列表。
async function searchCustomers(searchTerm) {
  try {
    const results = await payment.customers.search({ query: searchTerm });
    console.log(`“${searchTerm}”的搜索结果：`);
    results.list.forEach(customer => {
      console.log(`- ${customer.name} (ID: ${customer.id})`);
    });
  } catch (error) {
    console.error('搜索客户时出错：', error.message);
  }
}

searchCustomers('john');检索当前客户#根据 API 密钥或会话检索当前已认证客户的详细信息。
参数
无。
返回
返回已认证客户的 TCustomerExpanded 对象。
async function getCurrentCustomer() {
  try {
    const me = await payment.customers.me();
    console.log('当前客户：', me.name);
  } catch (error) {
    console.error('检索当前客户时出错：', error.message);
  }
}

getCurrentCustomer();检索逾期发票#检索特定客户的所有逾期发票列表。
参数
名称
类型
描述
id
string
客户的标识符。
返回
一个对象，其中包含客户详细信息、其逾期发票列表以及按货币和付款方式分组的逾期金额摘要。
async function getOverdueInvoices(customerId) {
  try {
    const overdueData = await payment.customers.overdueInvoices(customerId);
    console.log(`客户 ${overdueData.customer.name} 的逾期发票：`);
    overdueData.invoices.forEach(invoice => {
      console.log(`- 发票 ${invoice.id}，应付金额：${invoice.amount_due}`);
    });
    console.log('摘要：', overdueData.summary);
  } catch (error) {
    console.error('检索逾期发票时出错：', error.message);
  }
}

getOverdueInvoices('cus_xxxxxxxxxxxxxx');响应示例
{
  "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"
    }
  }
}
既然您已了解如何管理客户，接下来可以学习如何创建和管理他们的订阅。

属性	类型	描述
`id`	`string`	客户对象的唯一标识符。
`livemode`	`boolean`	指示对象是否存在于生产模式 (`true`) 或测试模式 (`false`)。
`did`	`string`	客户的去中心化身份标识（DID）。
`description`	`string`	您可以附加到客户对象的任意字符串。
`name`	`string`	客户的全名或企业名称。
`email`	`string`	客户的电子邮件地址。
`phone`	`string`	客户的电话号码。
`address`	`object`	客户的账单地址。请参阅下文的结构。
`shipping`	`object`	客户的配送信息。请参阅下文的结构。
`balance`	`string`	将应用于下一张发票的当前余额（如有）。负数余额表示贷方，正数余额表示借方。
`token_balance`	`object`	不同货币的代币余额记录。
`delinquent`	`boolean`	客户是否有逾期付款。
`metadata`	`object`	一组您可以附加到对象的键值对。
`invoice_prefix`	`string`	客户发票的前缀。
`created_at`	`Date`	对象创建时的时间戳。

属性	类型	描述
`city`	`string`	城市、区、郊区、城镇或村庄。
`country`	`string`	两位字母的国家代码（ISO 3166-1 alpha-2）。
`line1`	`string`	地址行 1（例如，街道、邮政信箱或公司名称）。
`line2`	`string`	地址行 2（例如，公寓、套房、单元或建筑物）。
`postal_code`	`string`	邮政编码。
`state`	`string`	州、县、省或地区。

名称	类型	描述
`id`	`string`	要更新的客户的标识符。
`data`	`object`	一个包含要更新字段的对象。有关可用字段（如 `name`、`email`、`description` 等），请参阅客户对象的属性。

名称	类型	描述
`did`	`string`	可选。用于筛选客户列表的 DID。
`page`	`number`	可选。用于分页的页码。
`pageSize`	`number`	可选。每页的项目数。默认为 20。
`order`	`string` or `string[]`	可选。对结果进行排序的顺序。示例：`'created_at:DESC'`。
`starting_after`	`string`	可选。用于分页的游标。`starting_after` 是一个对象 ID，用于定义您在列表中的位置。
`ending_before`	`string`	可选。用于分页的游标。`ending_before` 是一个对象 ID，用于定义您在列表中的位置。

名称	类型	描述
`query`	`string`	搜索查询字符串。API 将在 `name`、`email` 和 `description` 等字段中进行搜索。
`page`	`number`	可选。用于分页的页码。
`pageSize`	`number`	可选。每页的项目数。默认为 20。

概述

快速入门

核心概念

使用指南

API 参考

TypeScript 支持

客户

客户对象#

检索客户#

更新客户#

列出所有客户#

搜索客户#

检索当前客户#

检索逾期发票#

API 参考

产品

属性	类型	描述
`address`	`object`	配送地址，遵循地址对象结构。
`name`	`string`	收件人的姓名。
`phone`	`string`	收件人的电话号码。