メインコンテンツへスキップ

価格

Price オブジェクトは、特定の製品に対していくら、どのくらいの頻度で課金するかを定義します。これは、価格の金額と通貨を製品に関連付けます。例えば、1つの製品に複数の価格を設定でき、それぞれ異なる通貨や請求間隔を持つことができます。

Price オブジェクトは、特定の製品に対していくら、どのくらいの頻度で課金するかを定義します。これは、価格の金額と通貨を製品に関連付けます。例えば、1つの製品に複数の価格を設定でき、それぞれ異なる通貨や請求間隔を持つことができます。

このドキュメントでは、SDK を使用して Price オブジェクトを管理する方法について詳しく説明します。

Price オブジェクト

Price オブジェクトには、製品の価格設定モデルに関するすべての詳細が含まれています。

AttributeTypeDescription
idstringPrice オブジェクトの一意の識別子。
product_idstringこの価格が関連付けられている製品の ID。
productobject展開された Product オブジェクト。
activebooleanこの価格を新規購入に使用できるかどうか。
currency_idstringこの価格のデフォルト通貨の ID。
currencyobject展開された PaymentCurrency オブジェクト。
nicknamestring顧客に表示される価格の簡単な説明。
typestringone_time または recurring のいずれか。
unit_amountstring最小通貨単位での価格（例：USD の場合はセント）。
recurringobject継続的な価格の場合、このハッシュには請求間隔情報が含まれます。詳細は以下を参照してください。
lookup_keystring価格を取得するための、ユーザー定義の一意のキー。
metadataobjectオブジェクトに添付できるキーと値のペアのセット。
currency_optionsarray複数の通貨に対して異なる価格設定を指定します。
quantity_availablenumberこの価格で利用可能な合計数量。0 は無制限を意味します。
quantity_soldnumber販売されたユニット数。
quantity_limit_per_checkoutnumber顧客が1回のチェックアウトで購入できる最大数量。0 は制限なしを意味します。
upsellobject別の価格へのアップセルのための設定。

recurring オブジェクトのプロパティ

AttributeTypeDescription
intervalstringサブスクリプションが請求される頻度。day、week、month、year のいずれか。
interval_countnumberサブスクリプション請求間の間隔の数。
meter_idstring使用量ベースの請求に使用されるメーターの ID。

価格の作成

既存の製品に対して新しい価格を作成します。

Create a Price

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 (制限なし) です。

戻り値

新しく作成された Price オブジェクトを返します。

Response

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"
  }
}

価格の取得

既存の価格の詳細を取得します。

Retrieve a Price

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 も使用できます。

戻り値

要求された Price オブジェクトを返します。

価格の更新

渡されたパラメータの値を設定して、既存の価格を更新します。

Update a Price

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 のようなコア属性は変更できません。

戻り値

更新された Price オブジェクトを返します。

すべての価格を一覧表示

価格のリストを返します。価格は作成日順にソートされ、最新のものが最初に表示されます。

List Prices

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 です。

戻り値

Price オブジェクトの list、合計 count、および paging 情報を含むページ分割されたオブジェクトを返します。

価格の検索

クエリ文字列に一致する価格を検索します。

Search Prices

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 です。

戻り値

一致する Price オブジェクトの list を含むページ分割されたオブジェクトを返します。

価格のアーカイブ

価格をアーカイブし、新しいチェックアウトで使用されないようにします。価格が既に使用されている場合は、削除するよりもアーカイブする方が一般的に良い方法です。

Archive a Price

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 に設定された、アーカイブ済みの Price オブジェクトを返します。

価格の削除

価格を完全に削除します。この操作は元に戻せません。価格が取引で使用されたり、その他の理由でロックされている場合は削除できません。

Delete a Price

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 も使用できます。

戻り値

削除された Price オブジェクトを返します。

在庫の更新

価格の quantity_sold を手動で調整します。これは、標準のチェックアウトフロー以外で在庫を追跡するのに役立ちます。

Update Inventory

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 値を持つ、更新された Price オブジェクトを返します。