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

これらの例を使用して、Stripe オブジェクトにデータを保存します。

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

> PII、銀行口座の詳細、顧客のカードの詳細などの機密データは、`metadata` に含めないでください。

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

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

### 注文またはカートの ID

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

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

```curl
curl https://api.stripe.com/v1/checkout/sessions \
  -u "<<YOUR_SECRET_KEY>>:" \
  --data-urlencode "success_url=https://example.com/success" \
  -d mode=payment \
  -d "line_items[0][price]={{PRICE_ID}}" \
  -d "line_items[0][quantity]=1" \
  -d "metadata[cart_id]=cart_6943"
```

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

```json
{
  "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 (顧客)](https://docs.stripe.com/api/customers.md) を顧客管理システム (CMS) レコードに関連付けると、顧客の追跡と管理に役立ちます。

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

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

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

```json
{
  "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

[支払いインテント](https://docs.stripe.com/api/payment_intents.md)を直接作成すると、メタデータを使用してそれを [ 商品](https://docs.stripe.com/api/products.md)または [価格](https://docs.stripe.com/api/prices.md) に関連付けることができます。これにより、支払いインテントに関連付けたオブジェクトの ID を保存できますが、支払いインテントには価格や商品に関連付ける既存のフィールドがありません。

```curl
curl https://api.stripe.com/v1/payment_intents \
  -u "<<YOUR_SECRET_KEY>>:" \
  -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 を特定できます。その後、イベントのメタデータをダウンストリームのプロセス (注文のフルフィルメントや在庫管理など) に渡します。

```json
{
  "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
curl https://api.stripe.com/v1/payment_intents \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d amount=2000 \
  -d currency=usd \
  -d "automatic_payment_methods[enabled]=true" \
  -d "metadata[fulfillment_status]=fulfillment_not_started"
```

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

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

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

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

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

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

顧客がそのリンクを使用して購入を完了するたびに、Stripe は貴社がその決済用リンクに設定したメタデータを引き継いだ [Checkout Session](https://docs.stripe.com/api/checkout/sessions.md) を作成します。`checkout.session.completed` を監視して、顧客が購入を完了したときに Stripe から通知を受け取ることができます。その後、Checkout Session のメタデータから紹介元追跡データを引き出し、その売上がどの紹介によるものかを正確に特定できます。

```json
{
 "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](https://docs.stripe.com/api/customers.md) オブジェクトに追加します。

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

[Invoice (請求書)](https://docs.stripe.com/api/invoices.md) が無効化された理由の詳細を保存するには、`Invoice` オブジェクトの `metadata` を使用できます。

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

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

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

特定のオブジェクト作成エンドポイントには、メタデータ向けに複数のフィールドが含まれています。作成するオブジェクトにメタデータを直接保存するフィールドと、ダウンストリームで作成されたオブジェクトにメタデータを設定するフィールドがあります。詳細については、[間接メタデータフィールド](https://docs.stripe.com/metadata.md#set-indirectly)をご覧ください。

以下の例では、完了時にサブスクリプションを生成する [Checkoutセッション](https://docs.stripe.com/api/checkout/sessions.md)を作成します。これには、最上位の `metadata` フィールドと、`subscription_data.metadata` フィールドが使用されます。

```curl
curl https://api.stripe.com/v1/checkout/sessions \
  -u "<<YOUR_SECRET_KEY>>:" \
  --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 (サブスクリプション)](https://docs.stripe.com/api/subscriptions.md) オブジェクトに設定されます。これにより、メタデータが含まれるイベントが決まります。たとえば、`checkout.session.completed` など、Checkout セッションを含むイベントには、最上位の `metadata` パラメーターを介して指定された値が含まれます。

```json
{
  "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` フィールドに値を指定します。

```json
{
  "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](https://docs.stripe.com/api/invoices.md) イベントでアクセスできます。これは、サブスクリプションのメタデータが、サブスクリプションによって作成された`Invoice`オブジェクトの `subscription_details.metadata` に転送されるために発生します。

```json
{
  "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
curl https://api.stripe.com/v1/accounts \
  -u "<<YOUR_SECRET_KEY>>:" \
  --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 文字](https://docs.stripe.com/metadata.md#data) を超えるデータをオブジェクトに関連付けるには、超過したデータをご自身のデータベースに保存してください。その後メタデータを使用して、その情報にアクセスするための ID または検索キーを保存できます。このアプローチは、他のレコードの ID をシステムに保存する場合と似ています。

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

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

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

### Radar

Radar ルールを[参照メタデータ](https://docs.stripe.com/radar/rules/reference.md#metadata-attributes)の値に記述して、それを使用して、ルールが取引に関連付けられたアクションをトリガーするかどうかを決定できます。

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

[顧客](https://docs.stripe.com/api/customers.md)の最初の取引をレビュー対象としてフラグを立て、その後、顧客の詳細を更新して以降の取引をレビュー対象から除外するようフローを設定することができます。

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

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

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

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

#### テストルールの分割

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

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

```curl
curl https://api.stripe.com/v1/payment_intents \
  -u "<<YOUR_SECRET_KEY>>:" \
  -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](https://docs.stripe.com/search.md#metadata) を使用して、検索対象の[サポートされているオブジェクト](https://docs.stripe.com/search.md#supported-query-fields-for-each-resource)に設定したメタデータに基づいて、結果のクエリとフィルタリングを行います。

たとえば [Customer](https://docs.stripe.com/api/customers.md) オブジェクトにメタデータを追加して、「プレミアム」顧客を追跡できます。限定のプロモーションを提供するには、Search API を使用して `premium` とマークされた顧客を特定し、そのプロモーションを顧客に提供します。

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

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

オブジェクトを Search API の結果に表示するには、[インデックス付け](https://docs.stripe.com/search.md#data-freshness)を行う必要があります。インデックス付けが完了するまで、オブジェクトは検索結果に表示されません。