商品と価格の使い方

このページでは、PAY.JP のProduct (商品)APIとPrice (価格)APIを使った具体的な実装方法を説明します。

基本的な流れ

商品と価格を使用する基本的な流れは以下の流れに沿って実装します。

Product (商品)APIを作成する
その商品に紐付くPrice (価格)APIを作成する
決済時に価格IDを使用して支払いを行う

実装例

物販ECサイトの場合

商品として「Tシャツ」を登録し、3,000円の価格を設定する例です。

1. 商品を作成

ProductAPIAPI を使って商品を作成します。

curl https://api.pay.jp/v2/products \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Tシャツ",
    "description": "オリジナルデザインのTシャツ",
    "unit_label": "枚",
    "active": true
  }'

unit_label を設定することで、請求書や Checkout v2 で単位がユーザーにわかりやすく表示できます。
（例：「枚」や「着」、「ライセンス」や「ユーザー」など）

レスポンス例

{
  "id": "prod_xxxxx",
  "object": "product",
  "name": "Tシャツ",
  "description": "オリジナルデザインのTシャツ",
  "unit_label": "枚",
  "active": true,
  "default_price": null,
  ...
}

2. 価格を作成

PriceAPIAPI を使って価格を作成します。価格には紐づける商品を必ず指定する必要があります。

curl https://api.pay.jp/v2/prices \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "currency": "jpy",
    "unit_amount": 3000,
    "product": "prod_xxxxx"
  }'

レスポンス例

{
  "id": "price_xxxxx",
  "object": "price",
  "active": true,
  "currency": "jpy",
  "unit_amount": 3000,
  "product": "prod_xxxxx",
  "type": "one_time",
  ...
}

作成した価格は、Checkout SessionAPIの作成時に line_items[].price パラメーターで価格IDを指定することで支払いの作成ができます。

Checkout の使い方については外部リンク型決済を使うをご覧ください。

価格の付け替え

価格は作成後に金額を変更できません。金額を変更したい場合は、新しい価格を作成して付け替えます。

以下の例では、商品に設定された価格を新しい価格に付け替える手順を示しています。price_xxxxx のような ID は価格作成時に発行される実際の価格 ID に置き換えてください。

# 1. 新しい価格を作成
# レスポンスの id（例: price_new123）を控えておく
curl https://api.pay.jp/v2/prices \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "currency": "jpy",
    "unit_amount": 3500,
    "product": "prod_xxxxx"
  }'

# 2. 新しい価格をデフォルトに設定
# 手順1で取得した価格 ID を指定
curl https://api.pay.jp/v2/products/prod_xxxxx \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"default_price": "price_new123"}'

# 3. 既存の価格を無効化
# 古い価格 ID を指定して無効化
curl https://api.pay.jp/v2/prices/price_old456 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"active": false}'

デフォルト価格の設定を先に行うことで、一時的にアクティブなデフォルト価格が存在しない状態を回避できます。

次のステップ

外部リンク型決済を使うで商品と価格を使った決済フローを実装する