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

製品

製品オブジェクトは、顧客に提供する商品、サービス、またはデジタルクレジットを表します。これらはカタログ内のアイテムと考えることができます。各製品には1つ以上の価格を関連付けることができます。

このAPIを使用すると、製品カタログをプログラムで作成および管理できます。

これらの製品のコストと請求スキーマの管理に関する詳細は、価格 API リファレンス を参照してください。

製品オブジェクト

製品オブジェクトには、販売する単一のアイテムに関する詳細が含まれています。

AttributeTypeDescription
idstring製品オブジェクトの一意の識別子。
namestring製品名。顧客に表示されることを意図しています。
typestring製品のタイプ。service、good、または credit のいずれかです。デフォルトは service です。
activeboolean製品が現在購入可能かどうか。
descriptionstring製品を説明するために使用できる任意の文字列。
imagesstring[]製品画像のURL文字列のリスト。
metadataobjectオブジェクトに添付できるキーと値のペアのセット。追加情報を保存するのに役立ちます。
statement_descriptorstring顧客のクレジットカード明細書に表示されるオプションの記述子。
unit_labelstringこの製品の単一の単位を表すラベル（例：'user'、'license'）。
nft_factorystring製品がNFTにリンクされている場合のNFTファクトリーのアドレス。
featuresobject[]製品に関連付けられた機能のリスト。各機能オブジェクトには name プロパティがあります。
pricesPrice[]この製品に関連付けられた価格オブジェクトのリスト。これは、単一の製品を取得する場合または展開されたリストでのみ含まれます。
default_price_idstringこの製品のデフォルト価格のID。
created_atstringオブジェクトが作成されたときのタイムスタンプ。
updated_atstring最終更新のタイムスタンプ。

製品の作成

新しい製品オブジェクトを作成します。同時に、製品に対して1つ以上の価格を作成することもできます。

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クレジットカード明細書用の短い記述子。少なくとも1文字を含み、<、>、"、’、または \ を含めることはできません。最大22文字。
unit_labelstring製品の単一単位のラベル（例：'seat'、'GB'）。最大12文字。
nft_factorystring関連するNFTファクトリー契約のアドレス。
featuresobject[]機能オブジェクトのリスト。各オブジェクトには name プロパティがあります。
pricesobject[]この製品に作成して添付する価格オブジェクトの配列。以下の価格オブジェクトのプロパティテーブルを参照してください。

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

製品を作成する際に、価格の配列を含めることができます。prices 配列の各オブジェクトは、以下のプロパティを持つことができます。

NameTypeDescription
unit_amountnumber必須。最小通貨単位での価格（例：USDのセント）。0より大きい必要があります。
currency_idstring必須。この価格の通貨のID。
nicknamestring価格の内部向けの名前。
typestringone_time または recurring。デフォルトは one_time です。
recurringobjecttype が recurring の場合に必須。interval（day、week、month、または year）とオプションの interval_count を持つオブジェクト。
custom_unit_amountobject顧客が金額を選択できる価格を定義します。詳細は価格APIを参照してください。

戻り値

新しく作成された Product オブジェクトを返します。作成された価格のリストも含まれます。

Response Example

json
{
  "id": "prod_12345",
  "name": "Premium Subscription",
  "type": "service",
  "active": true,
  "description": "Monthly access to premium features.",
  "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": "Premium Subscription",
  "type": "service",
  "active": true,
  "description": "Monthly access to premium features.",
  // ... other product fields
  "prices": [
    // ... list of associated price objects
  ]
}

製品の更新

渡されたパラメーターの値を設定して、指定された製品を更新します。提供されていないパラメーターは変更されません。

Update Product

javascript
const product = await payment.products.update('prod_12345', {
  description: 'Updated: Monthly access to all premium features and priority support.',
  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": "Premium Subscription",
      // ... other product fields
    },
    {
      "id": "prod_67890",
      "name": "Standard Plan",
      // ... other product fields
    }
  ],
  "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。

戻り値

active ステータスが false（または既にアーカイブされていた場合は true）に設定された、更新後の Product オブジェクトを返します。

製品の削除

製品を永久に削除します。この操作は元に戻せません。製品は、価格がない場合、またはその価格がどの取引でも使用されていない場合にのみ削除できます。

Delete Product

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

パラメーター

NameTypeDescription
idstring必須。削除する製品のID。

戻り値

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