API 参考

产品

产品代表您向客户提供的商品、服务或数字项目。管理产品是建立支付系统的基础步骤。本文档详细介绍如何使用 Payment Kit SDK 创建、检索、更新、列出和管理产品。
定义产品后，您通常需要为其创建一个或多个价格。更多信息，请参阅价格 API 参考。
产品对象#产品对象包含您销售的商品的所有必要详细信息。
Attribute
Type
Description
id
string
产品的唯一标识符。
active
boolean
产品当前是否可供购买。
livemode
boolean
如果对象存在于线上模式，则为 true；如果存在于测试模式，则为 false。
locked
boolean
产品详情是否可以修改。默认为 false。
type
string
产品类型。可以是 service、good 或 credit。
name
string
产品名称，向客户显示。
description
string
产品描述，向客户显示。
images
string[]
产品图片的 URL 列表。
features
object[]
与产品关联的功能列表。每个功能对象都有一个 name 属性。
unit_label
string
产品单个单位的可选标签。
default_price_id
string
此产品的默认价格 ID。
metadata
object
一组用于存储附加信息的键值对。
statement_descriptor
string
一个可选的描述符，会显示在客户的银行对账单上。
created_at
Date
产品创建时的时间戳。
updated_at
Date
上次更新的时间戳。
创建产品#创建一个新产品。您也可以在同一次请求中创建关联的价格。
参数
Name
Type
Description
name
string
**必填。**产品名称。
type
string
**必填。**产品类型，例如 'service' 或 'good'。
description
string
产品的可选描述。
active
boolean
此产品是否激活。默认为 true。
images
string[]
产品的可选图片 URL 数组。
features
{ name: string }[]
一个可选的功能列表。
metadata
object
一组可选的键值数据。
prices
object[]
一个可选的价格对象数组，用于创建并附加到此产品。
示例
async function createProduct() {
  try {
    const product = await payment.products.create({
      name: 'Monthly Subscription',
      description: 'Standard monthly access to our service.',
      type: 'service',
      prices: [{
        unit_amount: '1000', // 例如，$10.00
        currency_id: 'usd_123abc',
        type: 'recurring',
        recurring: {
          interval: 'month',
          interval_count: 1
        }
      }]
    });
    console.log('产品已创建:', product);
  } catch (error) {
    console.error('创建产品时出错:', error);
  }
}

createProduct();响应示例
{
  "id": "prod_1J2K3L4M5N6O7P8Q",
  "active": true,
  "livemode": false,
  "locked": false,
  "type": "service",
  "name": "Monthly Subscription",
  "description": "Standard monthly access to our service.",
  "images": [],
  "features": [],
  "unit_label": null,
  "default_price_id": null,
  "metadata": {},
  "statement_descriptor": null,
  "created_at": "2023-10-27T10:00:00.000Z",
  "updated_at": "2023-10-27T10:00:00.000Z",
  "prices": [
    {
      "id": "price_A1B2C3D4E5F6G7H8",
      "active": true,
      "type": "recurring",
      "unit_amount": "1000",
      "currency_id": "usd_123abc",
      "recurring": {
        "interval": "month",
        "interval_count": 1
      }
    }
  ]
}检索产品#检索现有产品的详细信息。
参数
Name
Type
Description
id
string
**必填。**要检索的产品的唯一标识符。
示例
async function retrieveProduct(productId) {
  try {
    const product = await payment.products.retrieve(productId);
    console.log('已检索产品:', product);
  } catch (error) {
    console.error('检索产品时出错:', error);
  }
}

retrieveProduct('prod_1J2K3L4M5N6O7P8Q');响应示例
{
  "id": "prod_1J2K3L4M5N6O7P8Q",
  "active": true,
  "livemode": false,
  "locked": false,
  "type": "service",
  "name": "Monthly Subscription",
  "description": "Standard monthly access to our service.",
  "images": [],
  "features": [],
  "unit_label": null,
  "default_price_id": null,
  "metadata": {},
  "statement_descriptor": null,
  "created_at": "2023-10-27T10:00:00.000Z",
  "updated_at": "2023-10-27T10:00:00.000Z"
}更新产品#通过设置传入参数的值来更新指定产品。
参数
Name
Type
Description
id
string
**必填。**要更新的产品 ID。
updateData
object
**必填。**一个包含要更新字段的对象。
示例
async function updateProduct(productId) {
  try {
    const updatedProduct = await payment.products.update(productId, {
      description: 'Upgraded: Standard monthly access with priority support.',
      metadata: { 'tier': 'standard' }
    });
    console.log('产品已更新:', updatedProduct);
  } catch (error) {
    console.error('更新产品时出错:', error);
  }
}

updateProduct('prod_1J2K3L4M5N6O7P8Q');响应示例
{
  "id": "prod_1J2K3L4M5N6O7P8Q",
  "active": true,
  "description": "Upgraded: Standard monthly access with priority support.",
  "metadata": {
    "tier": "standard"
  },
  "updated_at": "2023-10-27T11:00:00.000Z"
}列出所有产品#返回产品的分页列表。产品按创建日期排序，最新创建的产品排在最前面。
参数
Name
Type
Description
active
boolean
可选。根据产品的激活状态进行筛选。
name
string
可选。根据产品名称筛选（不区分大小写）。
description
string
可选。根据产品描述筛选（不区分大小写）。
metadata.{key}
string
可选。根据特定的元数据键值对进行筛选。
page
number
可选。要检索的页码。
pageSize
number
可选。每页返回的产品数量。默认为 20。
order
string
可选。结果的排序顺序。例如：created_at:DESC。
示例
async function listProducts() {
  try {
    const productList = await payment.products.list({
      active: true,
      pageSize: 5
    });
    console.log('产品列表:', productList);
  } catch (error) {
    console.error('列出产品时出错:', error);
  }
}

listProducts();响应示例
{
  "count": 50,
  "list": [
    {
      "id": "prod_1J2K3L4M5N6O7P8Q",
      "name": "Monthly Subscription",
      "active": true
    },
    {
      "id": "prod_R9S8T7U6V5W4X3Y2",
      "name": "Annual Subscription",
      "active": true
    }
  ]
}搜索产品#搜索与给定查询字符串匹配的产品。
参数
Name
Type
Description
query
string
**必填。**搜索查询字符串。
page
number
可选。要检索的页码。
pageSize
number
可选。每页返回的产品数量。默认为 20。
示例
async function searchForProducts() {
  try {
    const results = await payment.products.search({ query: 'Subscription' });
    console.log('搜索结果:', results);
  } catch (error) {
    console.error('搜索产品时出错:', error);
  }
}

searchForProducts();归档产品#归档一个产品，使其变为非激活状态，不再可用于新的购买。这是一个可逆操作。
参数
Name
Type
Description
id
string
**必填。**要归档的产品 ID。
示例
async function archiveProduct(productId) {
  try {
    const product = await payment.products.archive(productId);
    console.log('产品已归档:', product.id, '激活状态:', product.active);
  } catch (error) {
    console.error('归档产品时出错:', error);
  }
}

archiveProduct('prod_1J2K3L4M5N6O7P8Q');删除产品#永久删除一个产品。此操作不可逆。
参数
Name
Type
Description
id
string
**必填。**要删除的产品 ID。
示例
async function deleteProduct(productId) {
  try {
    const result = await payment.products.del(productId);
    console.log('产品已删除:', result.id);
  } catch (error) {
    console.error('删除产品时出错:', error);
  }
}

deleteProduct('prod_1J2K3L4M5N6O7P8Q');

Attribute	Type	Description
`id`	`string`	产品的唯一标识符。
`active`	`boolean`	产品当前是否可供购买。
`livemode`	`boolean`	如果对象存在于线上模式，则为 `true`；如果存在于测试模式，则为 `false`。
`locked`	`boolean`	产品详情是否可以修改。默认为 `false`。
`type`	`string`	产品类型。可以是 `service`、`good` 或 `credit`。
`name`	`string`	产品名称，向客户显示。
`description`	`string`	产品描述，向客户显示。
`images`	`string[]`	产品图片的 URL 列表。
`features`	`object[]`	与产品关联的功能列表。每个功能对象都有一个 `name` 属性。
`unit_label`	`string`	产品单个单位的可选标签。
`default_price_id`	`string`	此产品的默认价格 ID。
`metadata`	`object`	一组用于存储附加信息的键值对。
`statement_descriptor`	`string`	一个可选的描述符，会显示在客户的银行对账单上。
`created_at`	`Date`	产品创建时的时间戳。
`updated_at`	`Date`	上次更新的时间戳。

Name	Type	Description
`name`	`string`	必填。产品名称。
`type`	`string`	必填。产品类型，例如 `'service'` 或 `'good'`。
`description`	`string`	产品的可选描述。
`active`	`boolean`	此产品是否激活。默认为 `true`。
`images`	`string[]`	产品的可选图片 URL 数组。
`features`	`{ name: string }[]`	一个可选的功能列表。
`metadata`	`object`	一组可选的键值数据。
`prices`	`object[]`	一个可选的价格对象数组，用于创建并附加到此产品。

Name	Type	Description
`active`	`boolean`	可选。根据产品的激活状态进行筛选。
`name`	`string`	可选。根据产品名称筛选（不区分大小写）。
`description`	`string`	可选。根据产品描述筛选（不区分大小写）。
`metadata.{key}`	`string`	可选。根据特定的元数据键值对进行筛选。
`page`	`number`	可选。要检索的页码。
`pageSize`	`number`	可选。每页返回的产品数量。默认为 `20`。
`order`	`string`	可选。结果的排序顺序。例如：`created_at:DESC`。

Name	Type	Description
`query`	`string`	必填。搜索查询字符串。
`page`	`number`	可选。要检索的页码。
`pageSize`	`number`	可选。每页返回的产品数量。默认为 `20`。

概述

快速入门

核心概念

使用指南

API 参考

TypeScript 支持

产品

产品对象#

创建产品#

检索产品#

更新产品#

列出所有产品#

搜索产品#

归档产品#

删除产品#

客户

价格

Name	Type	Description
`id`	`string`	必填。要更新的产品 ID。
`updateData`	`object`	必填。一个包含要更新字段的对象。