メタデータのユースケース

これらの一般的な例では、Metadata (メタデータ) を使用して重要なデータを Stripe オブジェクトに保存します。以下のユースケースはすべてを網羅したものではありません。メタデータの使用方法は、個別のユースケースによって異なります。

オブジェクトまたはレコードの ID を保存する

Stripe オブジェクトのメタデータを使用して、他のシステムのオブジェクトやレコードに属する ID を保存できます。これにより、Stripe オブジェクトと他のシステムからの関連リソースとの間で参照を構築できます。

注文またはカートの ID

顧客のカートを追跡する ID を作成すると、その ID をメタデータとして Checkout Sessions (Checkout セッション) に保存できます。これにより、決済プロセスの完了後に、関連する Stripe オブジェクトを使用して、システム内で関連付けられているカートを見つけることができます。

カート ID を作成した後、Checkout セッションのメタデータにカート ID を保存します。

curl https://api.stripe.com/v1/checkout/sessions \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  --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]"=cart_6943

次に、Checkout Session オブジェクトの ID を表示、更新、削除できます。これは、その Checkout セッションを含む Webhook エンドポイントに送信されたイベント (checkout.session.completed イベントを含む) にも表示されます。

{
  "id": "evt_1PYCL6CzbZon1zn9VivIehz7",
  "object": "event",
  "api_version": "2024-06-20",
  "created": 1719948368,
  "data": {
    "object": {
      "id": "cs_test_a1Znb7gdtlLEPzSi8qMIJzvsSPpIBMKFWovXx0h0O43WS411PpICgCqKjw",
      "object": "checkout.session",
      ...
      "metadata": {
        "cart_id": "cart_6943"
      },
      ...
    }
  },
  ...
  "type": "checkout.session.completed",
}

顧客または CMS ID

Stripe で作成した Customers (顧客) を顧客管理システム (CMS) レコードに関連付けると、顧客の追跡と管理に役立ちます。

Stripe で作成した Customer のメタデータに、CMS の顧客レコードの ID を保存します。

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

Stripe は、その Customer オブジェクトを含む Webhook エンドポイントに送信されるイベントに、この情報を含めます。たとえば、customer.updated イベントを受信すると、保存された ID を使用して、CMS で更新する必要があるレコードを特定できます。

{
  "id": "evt_1PajAGCzbZon1zn9FUsn7IoG",
  "object": "event",
  "api_version": "2024-06-20",
  "created": 1720551204,
  "data": {
    "object": {
      "id": "cus_QRcNyZh9aZHXnI",
      "object": "customer",
      ...
      "metadata": {
        "cms_id": "cust_6573"
      },
      ...
    }
  },
  ...
  "type": "customer.updated"
}

注文のフルフィルメントを追跡する

メタデータを使用して、注文のフルフィルメントプロセスを促進または追跡するデータを保存します。

支払いインテントの価格または商品 ID

Payment Intent (支払いインテント を直接作成すると、メタデータを使用して、それを Product (商品)または Price (価格) に関連付けることができます。これを使用して、支払いインテントに関連付けたオブジェクトの ID を保存できます。この ID には、オブジェクトを価格や商品に関連付ける既存のフィールドはありません。

curl https://api.stripe.com/v1/payment_intents \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d amount=2000 \
  -d currency=usd \
  -d "automatic_payment_methods[enabled]"=true \
  -d "metadata[price_id]"=price_1MoBy5LkdIwHu7ixZhnattbh \
  -d "metadata[product_id]"=prod_NWjs8kKbJWmuuc

payment_intent.succeeded イベントなど、その支払いインテントを含むイベントで関連付けられたオブジェクトの ID を特定できます。その後、イベントのメタデータをダウンストリームのプロセス (注文のフルフィルメントや在庫管理など) に渡します。

{
  "id": "evt_3PajIyCzbZon1zn90b9Wvsqf",
  "object": "event",
  "api_version": "2024-06-20",
  "created": 1720551759,
  "data": {
    "object": {
      "id": "pi_3PajIyCzbZon1zn901xQeOdi",
      "object": "payment_intent",
      ...
      "metadata": {
        "price_id": "price_1MoBy5LkdIwHu7ixZhnattbh",
        "product_id": "prod_NWjs8kKbJWmuuc"
      },
      ...
    }
  },
  ...
  "type": "payment_intent.succeeded",
}

フルフィルメントのステータスと追跡

注文のフルフィルメントフローを開始すると、メタデータを使用して、関連付けられた Stripe オブジェクトに現在のフルフィルメントのステータスを記録できます。これにより、Stripe からオブジェクトを取得でき、支払いのステータスとフルフィルメントの両方のステータスを同時に受信できます。

curl https://api.stripe.com/v1/payment_intents \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d amount=2000 \
  -d currency=usd \
  -d "automatic_payment_methods[enabled]"=true \
  -d "metadata[fulfillment_status]"=fulfillment_not_started

現在のフルフィルメントのステータスを更新するには、以下を行います。

curl https://api.stripe.com/v1/payment_intents/{{INTENT_ID}} \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d "metadata[fulfillment_status]"=shipping_label_created

アフィリエイトリンクを追跡する

一部のケースでは、Stripe は元のオブジェクトから関連オブジェクトに metadata をコピーします。サイトで Payment Links をホストするアフィリエイトがあり、それらのリンクから発生した売上に対してインセンティブを提供している場合は、この動作をアフィリエイトの追跡で使用できます。

決済用の URL リンクを作成する際に、metadata を入力してアフィリエイトを追跡できます。

curl https://api.stripe.com/v1/payment_links \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d "line_items[0][price]"=price_1MotwRLkdIwHu7ixYcPLm5uZ \
  -d "line_items[0][quantity]"=1 \
  -d "metadata[affiliate]"=afl_7920

顧客がそのリンクを使用して購入を完了するたびに、Stripe は Checkout Session (Checkout セッション) を作成します。これは、決済用の URL リンクで提供されたメタデータを継承します。checkout.session.completed イベントを監視して、顧客が購入を完了したときに Stripe から通知を受け取ることができます。そして、Checkout セッションのメタデータからアフィリエイトの追跡の詳細を取得して、売上を正確に帰属させることができます。

{
 "id": "evt_1PajfeCzbZon1zn9S7pNlQkU",
 "object": "event",
 "api_version": "2024-06-20",
 "created": 1720553150,
 "data": {
   "object": {
      "id": "cs_test_a1zgRtgzjvamTgTnqMqIaqP6zehBIkaM03iYzxNjZiJ7FMDRRhibd5w3gL",
      "object": "checkout.session",
      ...
      "metadata": {
        "affiliate": "afl_7920"
      },
      ...
    }
  },
  ...
  "type": "checkout.session.completed",
}

メモを保存する

メタデータを使用して、オブジェクトにメモを保存できます。たとえば、顧客の希望するコールタイムのメモを作成するには、メタデータを Customer オブジェクトに追加します。

curl https://api.stripe.com/v1/customers \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d name="Jenny Rosen" \
  --data-urlencode "metadata[call_window]"="10:00 AM - 2:00 PM"

Invoice (請求書) が無効化された理由の詳細を保存するには、Invoice オブジェクトの metadata を使用できます。

curl https://api.stripe.com/v1/invoices/{{INVOICE_ID}} \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  --data-urlencode "metadata[void_reason]"="Duplicate of Invoice #011"

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

メタデータの配置場所により、どのイベントタイプに提供する情報が含まれるかが決まります。同様に、構築済みのシステムで特定のイベントタイプを追跡する場合は、それによりメタデータの配置場所が決まります。

特定のオブジェクト作成エンドポイントには、メタデータ向けに複数のフィールドが含まれています。作成するオブジェクトにメタデータを直接保存するフィールドと、ダウンストリームで作成されたオブジェクトにメタデータを設定するフィールドがあります。詳細については、間接メタデータフィールドをご覧ください。

以下の例では、完了時にサブスクリプションを生成する Checkoutセッションを作成します。これには、最上位の metadata フィールドと、subscription_data.metadata フィールドが使用されます。

curl https://api.stripe.com/v1/checkout/sessions \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  --data-urlencode success_url="https://example.com/success" \
  -d mode=subscription \
  -d "line_items[0][price]"=price_1MotwRLkdIwHu7ixYcPLm5uZ \
  -d "line_items[0][quantity]"=1 \
  -d "metadata[checkout_metadata]"="Checkout Session metadata goes here" \
  -d "subscription_data[metadata][subscription_metadata]"="Subscription metadata goes here"

作成するオブジェクト (このケースでは Checkout セッション) にメタデータを設定できます。顧客が決済フロープロセスを完了すると、以前に subscription_data.metadata に指定されたメタデータが、新しく作成された Subscription (サブスクリプション) オブジェクトに設定されます。これにより、メタデータが含まれるイベントが決まります。たとえば、checkout.session.completed など、Checkout セッションを含むイベントには、最上位の metadata パラメーターを介して指定された値が含まれます。

{
  "id": "evt_1PakshCzbZon1zn9PlQwJYn0",
  "object": "event",
  "api_version": "2024-06-20",
  "created": 1720557803,
  "data": {
    "object": {
      "id": "cs_test_a1lsYmNYnEqQAxHT9knVy8v7u7m5ChjKtyB3M68ovMCjUQgCADsCkUviUU",
      "object": "checkout.session",
      ...
      "metadata": {
        "checkout_metadata": "Checkout Session metadata goes here"
      },
      ...
    }
  },
  ...
  "type": "checkout.session.completed",
}

customer.subscription.created など、Subscription オブジェクトを含むイベントには、subscription_data.metadata を介して提供された値が含まれます。ただし、そのイベントには Subscription オブジェクトが含まれるため、Stripe では Subscription オブジェクトの最上位の metadata フィールドに値を指定します。

{
  "id": "evt_1PaksgCzbZon1zn9x9u3MTSC",
  "object": "event",
  "api_version": "2024-06-20",
  "created": 1720557800,
  "data": {
    "object": {
      "id": "sub_1PaksdCzbZon1zn9D6DQjr9L",
      "object": "subscription",
      ...
      "metadata": {
        "subscription_metadata": "Subscription metadata goes here"
      },
      ...
    }
  },
  ...
  "type": "customer.subscription.created",
}

subscription_data.metadata で指定したメタデータには、Invoice イベントでアクセスできます。これは、サブスクリプションのメタデータが、サブスクリプションによって作成されたInvoiceオブジェクトの subscription_details.metadata に転送されるために発生します。

{
  "id": "evt_1PaksgCzbZon1zn9wD24BlvY",
  "object": "event",
  "api_version": "2024-06-20",
  "created": 1720557800,
  "data": {
    "object": {
      "id": "in_1PaksdCzbZon1zn9Z4bl0z7k",
      "object": "invoice",
      ...
      "subscription_details": {
        "metadata": {
          "subscription_metadata": "Subscription metadata goes here"
        }
        ...
      },
    }
  },
  ...
  "type": "invoice.finalized",
}

大量のメタデータを保存する

Stripe のメタデータフィールドを使用して、データを直接保存するか、外部検索キーを保存して固有のデータベースから追加データにアクセスして、取得する必要がある情報を最小限に抑えます。

構造化されたデータを保存する

メタデータは、JSON などの構造化データを表す文字列を含め、最大 [500 文字](/metadata#dataの任意の文字列を受け入れることができます。これを使用すると、メタデータフィールド内により多くのデータを格納でき、すべての情報を取得するためにアクセスする必要があるキーの数を減らすことができます。

curl https://api.stripe.com/v1/accounts \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  --data-urlencode "metadata[account_details]"="{\"sourcing_details\":{\"found_from\":\"web_search\",\"referrer\":\"user_123\",\"joined\":\"2024-01-01\"},\"tier_information\":{\"tier\":\"silver\",\"total_sales\":35,\"next_tier_at\":50,\"next_tier\":\"gold\"}}"

メタデータを外部に保存する

指定されたメタデータフィールドで許容される 500 文字 を超えるデータをオブジェクトに関連付けるには、超過したデータをご自身のデータベースに保存してください。その後メタデータを使用して、その情報にアクセスするための ID または検索キーを保存できます。このアプローチは、他のレコードの ID をシステムに保存する場合と似ています。

curl https://api.stripe.com/v1/accounts \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d "metadata[account_details_lookup_key]"=rec_a1b2c3

他の Stripe API とプロダクトでメタデータを使用する

メタデータを他の Stripe API およびプロダクトと使用して、柔軟性と拡張性を向上させることができます。

Radar

Radar ルールを参照メタデータの値に記述して、それを使用して、ルールが取引に関連付けられたアクションをトリガーするかどうかを決定できます。

顧客取引の最初のレビューを実行する

顧客の最初の取引をレビュー対象としてフラグを立て、その後、顧客の詳細を更新して以降の取引をレビュー対象から除外するようフローを設定することができます。

curl https://api.stripe.com/v1/customers \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d name="Jenny Rosen" \
  -d "metadata[verified_customer]"=false

Review if ::customer:verified_customer:: != 'true'

curl https://api.stripe.com/v1/customers/{{CUSTOMER_ID}} \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d "metadata[verified_customer]"=true

Stripe は、顧客の verified_customer が false に設定されている場合にのみ、支払いに対してこのルールをトリガーします。true に設定されている顧客は影響を受けません。

A/B テストのルール

Radar でメタデータを使用して、新しいルールの A/B テストシナリオを作成すると、新しいルールを顧客ベース全体に実装する前に、その効果を評価できます。

curl https://api.stripe.com/v1/payment_intents \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d amount=2000 \
  -d currency=usd \
  -d "automatic_payment_methods[enabled]"=true \
  -d "metadata[experiment_group]"=treatment

curl https://api.stripe.com/v1/payment_intents \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d amount=2000 \
  -d currency=usd \
  -d "automatic_payment_methods[enabled]"=true \
  -d "metadata[experiment_group]"=control

Block if ::experiment_group:: = 'treatment' and :card_funding: = 'prepaid'

Stripe は、処理グループの一部としてラベル付けされた支払いに対してのみこのルールをトリガーします。experiment_group として control に設定された支払いには影響しません。

Search API

Search API を使用して、検索対象のサポートされているオブジェクトに設定したメタデータに基づいて、結果のクエリとフィルタリングを行います。

たとえば Customer オブジェクトにメタデータを追加して、「プレミアム」顧客を追跡できます。限定のプロモーションを提供するには、Search API を使用して premium とマークされた顧客を特定し、そのプロモーションを顧客に提供します。

curl https://api.stripe.com/v1/customers \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d name="Jenny Rosen" \
  -d "metadata[service_tier]"=premium

curl -G https://api.stripe.com/v1/customers/search \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  --data-urlencode query="metadata['service_tier']:'premium'"

オブジェクトを Search API の結果に表示するには、インデックス付けを行う必要があります。インデックス付けが完了するまで、オブジェクトは検索結果に表示されません。