跳到主要內容

產品

產品物件代表您提供給客戶的商品、服務或數位點數。您可以將它們視為您目錄中的項目。每個產品可以有一個或多個相關聯的價格。

此 API 允許您以程式化方式建立和管理您的產品目錄。

有關管理這些產品的成本和計費方案的詳細資訊，請參閱 價格 API 參考。

產品物件

產品物件包含您銷售的單個項目的詳細資訊。

AttributeTypeDescription
idstring產品物件的唯一識別碼。
namestring產品的名稱，旨在向客戶顯示。
typestring產品的類型。可以是 service、good 或 credit。預設為 service。
activeboolean產品目前是否可供購買。
descriptionstring可用於描述產品的任意字串。
imagesstring[]產品圖片的 URL 字串列表。
metadataobject一組可以附加到物件上的鍵值對。可用於儲存額外資訊。
statement_descriptorstring顯示在您客戶信用卡帳單上的可選描述符。
unit_labelstring代表此產品單一單位的標籤（例如，「使用者」、「授權」）。
nft_factorystring如果產品連結到 NFT，則為 NFT 工廠的地址。
featuresobject[]與產品相關聯的功能列表。每個功能物件都有一個 name 屬性。
pricesPrice[]與此產品相關聯的價格物件列表。僅在檢索單個產品或在擴展列表中時包含此項。
default_price_idstring此產品的預設價格 ID。
created_atstring物件建立時的時間戳。
updated_atstring最後更新的時間戳。

建立產品

建立一個新的產品物件。您也可以同時為該產品建立一個或多個價格。

Create Product

javascript
const product = await payment.products.create({
  name: 'Premium Subscription',
  description: 'Monthly access to premium features.',
  type: 'service',
  prices: [
    {
      unit_amount: 1500, // e.g., 15.00 USD
      currency_id: 'usd_xxxx',
      type: 'recurring',
      recurring: {
        interval: 'month',
        interval_count: 1,
        usage_type: 'licensed'
      },
    },
  ],
});

參數

NameTypeDescription
namestring必填。產品的名稱。
typestring產品類型。service、good 或 credit 之一。預設為 service。
descriptionstring一個可選的、面向使用者的產品描述。
imagesstring[]產品圖片的 URL 列表。
metadataobject與產品一起儲存的鍵值資料。
statement_descriptorstring信用卡帳單的簡短描述符。必須至少包含一個字母，且不能包含 <、>、"、’ 或 \。最多 22 個字元。
unit_labelstring產品單一單位的標籤（例如，「席位」、「GB」）。最多 12 個字元。
nft_factorystring關聯的 NFT 工廠合約地址。
featuresobject[]功能物件列表，其中每個物件都有一個 name 屬性。
pricesobject[]要建立並附加到此產品的價格物件陣列。請參閱下方的 價格物件屬性 表格。

價格物件屬性

建立產品時，您可以包含一個價格陣列。prices 陣列中的每個物件可以具有以下屬性：

NameTypeDescription
unit_amountnumber必填。以最小貨幣單位表示的價格（例如，美元的美分）。必須大於 0。
currency_idstring必填。此價格的貨幣 ID。
nicknamestring價格的內部名稱。
typestringone_time 或 recurring。預設為 one_time。
recurringobject如果 type 為 recurring 則為必填。一個包含 interval（day、week、month 或 year）和可選 interval_count 的物件。
custom_unit_amountobject定義一個客戶可以選擇金額的價格。詳情請參閱價格 API。

傳回

傳回新建立的 Product 物件，包括任何已建立的價格列表。

Response Example

json
{
  "id": "prod_12345",
  "name": "高級訂閱",
  "type": "service",
  "active": true,
  "description": "每月存取高級功能。",
  "images": [],
  "metadata": {},
  "statement_descriptor": null,
  "unit_label": null,
  "nft_factory": null,
  "features": [],
  "default_price_id": "price_67890",
  "created_at": "2023-10-27T10:00:00.000Z",
  "updated_at": "2023-10-27T10:00:00.000Z",
  "prices": [
    {
      "id": "price_67890",
      "product_id": "prod_12345",
      "active": true,
      "type": "recurring",
      "unit_amount": "1500",
      "currency_id": "usd_xxxx",
      "recurring": {
        "interval": "month",
        "interval_count": 1
      }
    }
  ]
}

檢索產品

檢索現有產品的詳細資訊。

Retrieve Product

javascript
const product = await payment.products.retrieve('prod_12345');

參數

NameTypeDescription
idstring必填。要檢索的產品的唯一識別碼。

傳回

如果提供了有效的 ID，則傳回一個 Product 物件。否則，此呼叫將傳回錯誤。

Response Example

json
{
  "id": "prod_12345",
  "name": "高級訂閱",
  "type": "service",
  "active": true,
  "description": "每月存取高級功能。",
  // ... 其他產品欄位
  "prices": [
    // ... 相關價格物件列表
  ]
}

更新產品

透過設定傳遞的參數值來更新指定的產品。任何未提供的參數將保持不變。

Update Product

javascript
const product = await payment.products.update('prod_12345', {
  description: '更新：每月存取所有高級功能和優先支援。',
  metadata: { 'tier': 'premium' }
});

參數

NameTypeDescription
idstring必填。要更新的產品 ID。
namestring產品的名稱。
descriptionstring一個可選的、面向使用者的產品描述。
imagesstring[]產品圖片的 URL 列表。
metadataobject與產品一起儲存的鍵值資料。
statement_descriptorstring信用卡帳單的簡短描述符。
default_price_idstring要設定為此產品預設價格的價格 ID。
unit_labelstring產品單一單位的標籤。
featuresobject[]功能物件列表。

傳回

傳回更新後的 Product 物件。

列出所有產品

傳回分頁的產品列表。產品按建立日期排序，最新建立的產品排在最前面。

List Products

javascript
const products = await payment.products.list({
  active: true,
  limit: 10
});

參數

NameTypeDescription
activeboolean僅傳回具有此活動狀態的產品。
namestring僅傳回具有此名稱的產品。
descriptionstring僅傳回具有此描述的產品。
typestring僅傳回此類型的產品（例如，credit）。
metadata.{key}string按中繼資料中的特定鍵值對進行篩選。例如，metadata.tier: 'premium'。
pagenumber要檢索的頁碼。預設為 1。
pageSizenumber每頁傳回的物件數量。預設為 20。

傳回

一個分頁的 Product 物件列表。

Response Example

json
{
  "count": 50,
  "list": [
    {
      "id": "prod_12345",
      "name": "高級訂閱",
      // ... 其他產品欄位
    },
    {
      "id": "prod_67890",
      "name": "標準方案",
      // ... 其他產品欄位
    }
  ],
  "paging": {
    "page": 1,
    "pageSize": 20
  }
}

搜尋產品

傳回符合搜尋查詢的產品列表。

Search Products

javascript
const products = await payment.products.search({ query: 'Premium' });

參數

NameTypeDescription
querystring搜尋查詢字串。搜尋將在 name 和 description 等欄位上執行。
pagenumber要檢索的頁碼。預設為 1。
pageSizenumber每頁傳回的物件數量。預設為 20。

傳回

符合搜尋查詢的分頁 Product 物件列表。

封存產品

封存一個產品，使其無法進行新的購買。此操作會切換產品的 active 狀態。封存產品不會影響現有的訂閱或購買。

Archive Product

javascript
const product = await payment.products.archive('prod_12345');

參數

NameTypeDescription
idstring必填。要封存的產品 ID。

傳回

傳回更新後的 Product 物件，其 active 狀態設定為 false（如果已封存，則設定為 true）。

刪除產品

永久刪除一個產品。此操作無法撤銷。只有在產品沒有價格，或者其所有價格都未在任何交易中使用時，才能刪除該產品。

Delete Product

javascript
const deletedProduct = await payment.products.del('prod_12345');

參數

NameTypeDescription
idstring必填。要刪除的產品 ID。

傳回

傳回已刪除的 Product 物件。