メタデータ

各種リソースに任意のデータを保存できるメタデータ機能の使い方

メタデータとは

メタデータは PAY.JP の各種リソース（支払い、顧客、商品など）に任意のデータをキーバリュー形式で保存できる機能です。自社システムの ID や EC サイトの注文情報を PAY.JP のオブジェクトと紐づけるなど、柔軟な用途で利用できます。

基本的な使い方

メタデータは JSON オブジェクトとして各リソースの metadata フィールドに設定します。

データ型

メタデータの値としては JSON として扱える以下のデータ型がサポートされています

文字列（string）
整数（integer）
真偽値（boolean）

配列やネストされたオブジェクトは使用できません。

制約事項

メタデータには以下の制約があります。

項目	制約
キー	1つのキーあたり最大40文字
値	1つの値あたり最大500文字（文字列の場合）
キー数	1つのオブジェクトあたり最大20個

使用方法

メタデータの作成

各種リソースの作成時に、 metadata キーにオブジェクトとして指定することでメタデータを設定できます。

以下は Checkout Session を作成する際にメタデータを設定する例です。

curl https://api.pay.jp/v2/checkout/sessions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "success_url": "https://example.com/success",
    "line_items": [
      {
        "price": "price_xxxxx",
        "quantity": 1
      }
    ],
    "mode": "payment",
    "metadata": {
      "order_id": "order_12345",
      "campaign": "summer_sale",
      "quantity": 3,
      "is_gift": true
    }
  }'

メタデータの取得

メタデータをセットしたリソースを取得すると、セットしたメタデータがレスポンスに含まれています。

{
  "id": "cs_xxxxxxxxxxxxx",
  "object": "checkout.session",
  "metadata": { 
    "order_id": "order_12345",
    "campaign": "summer_sale",
    "quantity": 3,
    "is_gift": true
  },
  ...
}

メタデータの更新

メタデータを更新する場合、既存のキーに対して新しい値を送信すると、設定済みの値が上書きされます。既存のキーを指定しなかった場合はそのまま保持されます。

以下の場合、既存のメタデータは保持されたまま、新しいキー（total_orders, is_vip）が追加されます。

# 新しいキーを追加
curl https://api.pay.jp/v2/customers/cus_xxxxx \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "metadata": {
      "total_orders": 5,
      "is_vip": true
    }
  }'

メタデータの削除

特定のキーを削除するには、そのキーに空の値を送信します。

curl https://api.pay.jp/v2/customers/cus_xxxxx \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "metadata": {
      "campaign": "",
    }
  }'

メタデータの間接的な設定

Checkout Session 作成時に引数として payment_flow_data.metadata または setup_flow_data.metadata を指定すると、 Payment Flow または Setup Flow が生成される際に、そのデータがリソースのメタデータとして自動的に引き継がれます。

メタデータ

On this page