メタデータ

Metadata (メタデータ) は、特定の Stripe オブジェクトの属性であり、キーと値のペアの形式で構造化された多くの情報をオブジェクトに格納して、自社で使用したり、参照したりすることができます。たとえば、お客様のシステムにおけるユーザーの一意の識別子を、Stripe の Customer (顧客) オブジェクトに保存できます。

設定

データ

以下のデータ制限内で合計 50 件のキーと値のペアを追加できます。

• キー: 上限 40 文字。角括弧 ([ ]) はキーに含めることができません。
• 値: 上限 500 文字。

システムでこれ以上の領域が必要な場合は、データを外部データベースに保存し、キーと値のペアを使用して外部オブジェクトの ID を metadata に保存します。

Radar でメタデータを使用する場合を除き、 Stripe は支払いのオーソリや拒否などにはメタデータを使用しません。また、表示することを希望しない限り、メタデータは顧客に表示されません。

リクエスト

Stripeは、リクエストでシークレットキーを使用した場合にのみメタデータを返します。Stripe.js やモバイル SDK のクライアント側のリクエストなど、公開可能なキーのリクエストに応じてオブジェクトからのメタデータを非表示にします。

メタデータを追加および更新する

API を使用して、メタデータにキーと値のペアを追加し、メタデータの値を更新し、キーを置き換えます。さまざまなアクションを 1 つのリクエストに組み合わせて、複数のメタデータの追加、更新、削除を同時に実行できます。

キーと値のペアを追加する

オブジェクトを作成するときにメタデータにキーと値のペアを追加するには、オブジェクト作成リクエストでキーと値を指定します。

curl https://api.stripe.com/v1/customers \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d name="Jenny Rosen" \
  -d "metadata[cms_id]"=6573

{
  "id": "cus_NffrFeUfNV2Hib",
  "object": "customer",
  ...
  "metadata": {
    "cms_id": "6573"
  },
  ...
}

既存のメタデータにキーと値のペアを追加する

既存のオブジェクトのメタデータにキーと値のペアを追加するには、更新リクエストでキーと値を指定します。

curl https://api.stripe.com/v1/customers/{{CUSTOMER_ID}} \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d "metadata[loyalty_program]"=no

{
  "id": "cus_NffrFeUfNV2Hib",
  "object": "customer",
  ...
  "metadata": {
    "cms_id": "6573"
  },
  ...
}

{
  "id": "cus_NffrFeUfNV2Hib",
  "object": "customer",
  ...
  "metadata": {
      "loyalty_program": "no",
      "cms_id": "6573"
  },
  ...
}

メタデータ値を更新する

メタデータ内の既存のキーの値を更新するには、既存のキーを使用して新しい値を渡します。たとえば、既存のキーと値のペア "loyalty_program": "no" を "loyalty_program": "yes" に更新して、Customer (顧客) オブジェクトを更新できます。

curl https://api.stripe.com/v1/customers/{{CUSTOMER_ID}} \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d "metadata[loyalty_program]"=yes

{
  "id": "cus_NffrFeUfNV2Hib",
  "object": "customer",
  ...
  "metadata": {
    "loyalty_program": "no"
  },
  ...
}

{
  "id": "cus_NffrFeUfNV2Hib",
  "object": "customer",
  ...
  "metadata": {
    "loyalty_program": "yes"
  },
  ...
}

メタデータキーを更新する

既存の値を持つキーを更新するには、キーを削除し、その値を新しいキーに渡します。たとえば、Customer (顧客) オブジェクトを更新して、その "loyalty_program" キーを削除し、キーの値 "yes" を新しい "rewards_program" キーに渡すことができます。

curl https://api.stripe.com/v1/customers/{{CUSTOMER_ID}} \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d "metadata[loyalty_program]"= \
  -d "metadata[rewards_program]"=yes

{
  "id": "cus_NffrFeUfNV2Hib",
  "object": "customer",
  ...
  "metadata": {
    "loyalty_program": "yes"
  },
  ...
}

{
  "id": "cus_NffrFeUfNV2Hib",
  "object": "customer",
  ...
  "metadata": {
    "rewards_program": "yes"
  },
  ...
}

メタデータを削除する

API を使用して、1 つのキーまたはキーセット全体を削除します。

1 つのキーを削除する

メタデータからキーを削除するには、値として空の文字列をキーに渡します。

curl https://api.stripe.com/v1/customers/{{CUSTOMER_ID}} \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d "metadata[loyalty_program]"=yes \
  -d "metadata[loyalty_member_id]"=

{
  "id": "cus_NffrFeUfNV2Hib",
  "object": "customer",
  ...
  "metadata": {
    "loyalty_program": "yes",
    "loyalty_member_id": "12345678"
  },
  ...
}

{
  "id": "cus_NffrFeUfNV2Hib",
  "object": "customer",
  ...
  "metadata": {
    "loyalty_program": "yes"
  },
  ...
}

すべてのキーを削除する

すべてのキーを同時に削除するには、metadata 属性の値として空のオブジェクトを渡します。

curl https://api.stripe.com/v1/customers/
{{CUSTOMER_ID}}
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
  -d "metadata"=""

{
  "id": "cus_NffrFeUfNV2Hib",
  "object": "customer",
  ...
  "metadata": {
    "loyalty_program": "yes",
    "loyalty_member_id": "12345678"
  },
  ...
}

{
  "id": "cus_NffrFeUfNV2Hib",
  "object": "customer",
  ...
  "metadata": {}
  ...
}

メタデータを別のオブジェクトにコピーする

オブジェクトのメタデータの関連するオブジェクトへのコピーは自動的には行われません。オブジェクトのメタデータを表示するには、そのオブジェクトを調べる必要があります。関連オブジェクトからメタデータを取得するには、カスタムロジックを構築して、関連オブジェクトを見つけて調べます。メタデータをあるオブジェクトから別のオブジェクトに明示的にコピーするには、自社でフローを構築する必要があります。

例外

一部のケースでは、後方互換性やその他の固有のシナリオのために、Stripe はオブジェクト間でメタデータをコピーします。

メタデータを間接的に設定する

一部のエンドポイントは、別のパラメーター内にネストされた metadata パラメーターを受け入れます。オブジェクトを作成する際にこれらのパラメーターを使用して、基になるオブジェクトにメタデータを設定できます。たとえば、Checkout セッションを作成する際に payment_intent_data.metadata を使用して、セッションが作成する基になる支払いインテントにメタデータを提供し、設定することができます。

イベントと Webhook エンドポイント

Stripe が Webhook エンドポイントに Event (イベント) を送信すると、対応するオブジェクトとオブジェクトに含まれるメタデータが格納されます。これにより、Webhook ハンドラは、Stripe オブジェクトに設定されたメタデータを受け取り、それを注文のフルフィルメントなどのダウンストリームのプロセスに渡すことができます。

たとえば、顧客が Checkout セッション を使用して購入したときにカート ID を含めるには、Checkout セッションの作成時にメタデータとして指定します。

curl https://api.stripe.com/v1/checkout/sessions \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  --data-urlencode success_url="https://example.com/success" \
  -d mode=payment \
  -d "line_items[0][price]"=price_1MotwRLkdIwHu7ixYcPLm5uZ \
  -d "line_items[0][quantity]"=1 \
  -d "metadata[cart_id]"=6943

顧客が決済プロセスを完了すると、Webhook エンドポイントに Checkout Session オブジェクトのメタデータが含まれた checkout.session.completed イベントが送信されます。そのイベントをリッスンするように Webhook を設定し、メタデータにアクセスしてデータを処理する際に使用できるようにする必要があります。

{
  "id": "evt_1P8pqUAgEBCHsfP6JfNctbLv",
  "object": "event",
  "api_version": "2022-11-15",
  "created": 1713903702,
  "data": {
    "object": {
      "id": "cs_test_a1aDQuoXLoddIOV9iOvZRgKAtPoRIfFkYHBWxF9AQAPlGG3STB1ndqqaUw",
      "object": "checkout.session",
      ...
      "metadata": {
        "cart_id": "6943"
      },

メタデータを検索する

特定の書式を使用して、サポート対象のオブジェクトに既存のメタデータを検索できます。これには、メタデータフィールドに特定の値があるレコードの検索や、オブジェクトにメタデータキーが存在するかどうかの確認が含まれます。メタデータの検索で詳細をご確認ください。

メタデータと Radar を使用して不正利用を防止する

Radar でメタデータを使用して、不正利用の防止に役立つカスタムルールを作成します。詳しくは、Radar のメタデータ属性をご覧ください。