跳到主要內容

價格

價格物件定義了特定產品的收費金額和頻率。它將價格金額和貨幣與產品關聯起來。例如，一個產品可能有多個價格，每個價格使用不同的貨幣或有不同的計費週期。

價格物件定義了特定產品的收費金額和頻率。它將價格金額和貨幣與產品關聯起來。例如，一個產品可能有多個價格，每個價格使用不同的貨幣或有不同的計費週期。

本文件詳細說明如何使用 SDK 管理價格物件。

價格物件

一個價格物件包含產品定價模型的所有詳細資訊。

AttributeTypeDescription
idstring價格物件的唯一識別碼。
product_idstring此價格關聯的產品 ID。
productobject展開的產品物件。
activeboolean此價格是否可用於新的購買。
currency_idstring此價格的預設貨幣 ID。
currencyobject展開的 PaymentCurrency 物件。
nicknamestring價格的簡短描述，會向客戶顯示。
typestringone_time 或 recurring 其中之一。
unit_amountstring以最小貨幣單位表示的價格（例如，美元的美分）。
recurringobject對於週期性價格，此雜湊包含計費週期資訊。詳情請見下方。
lookup_keystring使用者定義的唯一鍵，用於檢索價格。
metadataobject一組您可以附加到物件上的鍵值對。
currency_optionsarray指定多種貨幣的不同定價。
quantity_availablenumber此價格的總可用數量。0 表示無限制。
quantity_soldnumber已售出的單位數量。
quantity_limit_per_checkoutnumber客戶在單次結帳中可購買的最大數量。0 表示無限制。
upsellobject用於向上銷售至另一價格的設定。

recurring 物件屬性

AttributeTypeDescription
intervalstring訂閱的計費頻率。day、week、month 或 year 其中之一。
interval_countnumber訂閱計費之間的間隔數。
meter_idstring用於基於用量計費的計量器 ID。

建立價格

為現有產品建立一個新價格。

建立價格

javascript
async function createPrice() {
  try {
    const price = await payment.prices.create({
      product_id: 'prod_xxxxxxxxxxxxxx',
      unit_amount: 1500, // 例如，$15.00
      currency_id: 'usd_xxxxxxxxxxxxxx',
      type: 'recurring',
      recurring: {
        interval: 'month',
        interval_count: 1,
        usage_type: 'licensed'
      },
      nickname: 'Monthly Pro Plan',
      lookup_key: 'pro_monthly_usd',
    });
    console.log('價格已建立:', price);
  } catch (error) {
    console.error('建立價格時發生錯誤:', error.message);
  }
}

createPrice();

參數

NameTypeDescription
product_idstring必需。 此價格所屬產品的 ID。
unit_amountnumber必需。 要收取的金額，以最小貨幣單位表示。
currency_idstring必需。 此價格的貨幣 ID。
typestring定價類型。可以是 one_time 或 recurring。預設為 one_time。
activeboolean價格是否啟用。預設為 true。
nicknamestring價格的內部名稱。
lookup_keystring用於參照價格的唯一字串。
recurringobject包含週期性計費資訊的物件。如果 type 為 recurring，則為必需。
currency_optionsarray一個物件陣列，用於指定不同貨幣的價格。
metadataobject與價格一起儲存的鍵值資料。
quantity_availablenumber總可用數量。預設為 0 (無限制)。
quantity_limit_per_checkoutnumber每次結帳的最大數量。預設為 0 (無限制)。

返回值

返回新建立的價格物件。

回應

json
{
  "id": "price_xxxxxxxxxxxxxx",
  "product_id": "prod_xxxxxxxxxxxxxx",
  "active": true,
  "currency_id": "usd_xxxxxxxxxxxxxx",
  "nickname": "Monthly Pro Plan",
  "type": "recurring",
  "unit_amount": "1500",
  "recurring": {
    "interval": "month",
    "interval_count": 1,
    "meter_id": null
  },
  "lookup_key": "pro_monthly_usd",
  "metadata": {},
  "product": {
    "id": "prod_xxxxxxxxxxxxxx",
    "name": "Pro Plan"
  },
  "currency": {
    "id": "usd_xxxxxxxxxxxxxx",
    "name": "United States Dollar"
  }
}

檢索價格

檢索現有價格的詳細資訊。

檢索價格

javascript
async function retrievePrice(priceId) {
  try {
    const price = await payment.prices.retrieve(priceId);
    console.log('已檢索價格:', price);
  } catch (error) {
    console.error('檢索價格時發生錯誤:', error.message);
  }
}

retrievePrice('price_xxxxxxxxxxxxxx');

參數

NameTypeDescription
idstring必需。 要檢索的價格的唯一識別碼。也可以是 lookup_key。

返回值

返回所請求的價格物件。

更新價格

透過設定傳入參數的值來更新現有價格。

更新價格

javascript
async function updatePrice(priceId) {
  try {
    const price = await payment.prices.update(priceId, {
      nickname: 'Updated Pro Plan Nickname',
      metadata: { order_id: '6735' },
    });
    console.log('價格已更新:', price);
  } catch (error) {
    console.error('更新價格時發生錯誤:', error.message);
  }
}

updatePrice('price_xxxxxxxxxxxxxx');

參數

NameTypeDescription
idstring必需。 要更新的價格 ID。也可以是 lookup_key。
updatesobject一個包含要更新欄位的物件。可更新欄位列表請參見建立方法。注意：如果價格已被使用 (locked)，則無法更改 unit_amount 和 recurring 等核心屬性。

返回值

返回更新後的價格物件。

列出所有價格

返回您的價格列表。價格按建立日期排序，最新建立的價格會最先顯示。

列出價格

javascript
async function listPrices() {
  try {
    const prices = await payment.prices.list({
      product_id: 'prod_xxxxxxxxxxxxxx',
      active: true,
      limit: 5,
    });
    console.log('已檢索價格:', prices.list);
  } catch (error) {
    console.error('列出價格時發生錯誤:', error.message);
  }
}

listPrices();

參數

NameTypeDescription
activeboolean僅返回具有此啟用狀態的價格。
typestring僅返回此類型的價格，例如 recurring。
currency_idstring僅返回此貨幣 ID 的價格。
product_idstring僅返回此產品 ID 的價格。
lookup_keystring僅返回具有此查找鍵的價格。
pagenumber分頁的頁碼。預設為 1。
pageSizenumber每頁的項目數。預設為 20。

返回值

返回一個分頁物件，其中包含價格物件的 list、總 count 和 paging 資訊。

搜尋價格

搜尋與查詢字串相符的價格。

搜尋價格

javascript
async function searchPrices() {
  try {
    const prices = await payment.prices.search({ query: 'Pro Plan' });
    console.log('搜尋結果:', prices.list);
  } catch (error) {
    console.error('搜尋價格時發生錯誤:', error.message);
  }
}

searchPrices();

參數

NameTypeDescription
querystring搜尋查詢字串。
pagenumber分頁的頁碼。預設為 1。
pageSizenumber每頁的項目數。預設為 20。

返回值

返回一個分頁物件，其中包含相符的價格物件 list。

封存價格

封存一個價格，使其無法在新的結帳中使用。如果一個價格已被使用，通常封存它比刪除它更好。

封存價格

javascript
async function archivePrice(priceId) {
  try {
    const price = await payment.prices.archive(priceId);
    console.log('價格已封存:', price.id, '啟用:', price.active);
  } catch (error) {
    console.error('封存價格時發生錯誤:', error.message);
  }
}

archivePrice('price_xxxxxxxxxxxxxx');

參數

NameTypeDescription
idstring必需。 要封存的價格 ID。也可以是 lookup_key。

返回值

返回已封存的價格物件，其 active 設為 false。

刪除價格

永久刪除一個價格。此操作無法復原。如果價格已在交易中使用或因其他原因被鎖定，則無法刪除。

刪除價格

javascript
async function deletePrice(priceId) {
  try {
    const deletedPrice = await payment.prices.del(priceId);
    console.log('價格已刪除:', deletedPrice.id);
  } catch (error) {
    console.error('刪除價格時發生錯誤:', error.message);
  }
}

deletePrice('price_xxxxxxxxxxxxxx');

參數

NameTypeDescription
idstring必需。 要刪除的價格 ID。也可以是 lookup_key。

返回值

返回已刪除的價格物件。

更新庫存

手動調整價格的 quantity_sold。這對於在標準結帳流程之外追蹤庫存很有用。

更新庫存

javascript
async function updateInventory(priceId) {
  try {
    // 將已售數量增加 2
    const price = await payment.prices.inventory(priceId, {
      quantity: 2,
      action: 'increment',
    });
    console.log('庫存已更新。新的已售數量:', price.quantity_sold);
  } catch (error) {
    console.error('更新庫存時發生錯誤:', error.message);
  }
}

updateInventory('price_xxxxxxxxxxxxxx');

參數

NameTypeDescription
idstring必需。 價格的 ID。
paramsobject一個包含庫存調整詳細資訊的物件。

params 物件屬性

NameTypeDescription
quantitynumber必需。 用於調整已售數量的金額。
actionstring必需。 調整操作。必須是 increment 或 decrement。

返回值

返回更新後的價格物件，其中包含新的 quantity_sold 值。