# メタデータ

メタデータを使用して追加情報を保存する方法をご紹介します。

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

## 設定

### データ

顧客に 1 つのフィールドを表示する場合は、`description` の使用を検討してください。

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

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

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

[Radar](https://docs.stripe.com/radar.md) でメタデータを使用する場合を除き、 Stripe は支払いのオーソリや拒否などにはメタデータを使用しません。また、表示することを希望しない限り、メタデータは顧客に表示されません。

> 銀行口座情報やクレジットカードの詳細などの機密情報は、メタデータに保存しないでください。

### リクエスト

Stripeは、リクエストで[シークレットキー](https://docs.stripe.com/keys.md#obtain-api-keys)を使用した場合にのみメタデータを返します。Stripe.js やモバイル SDK のクライアント側のリクエストなど、公開可能なキーのリクエストに応じてオブジェクトからのメタデータを非表示にします。

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

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

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

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

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

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

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

既存のオブジェクトのメタデータにキーと値のペアを追加するには、更新リクエストでキーと値を指定します。このパラメーターはマージメカニズムを使用するため、既存のメタデータに影響を与えることなく、更新コールで新しいキーと値のペアをオブジェクトに追加できます。たとえば、`Customer` オブジェクトに `key1` と `key2` がある場合、これを更新して `key3` を追加すると、更新されたオブジェクトには 3 つすべてのキーが含まれます。

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

### Before

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

### After

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

### メタデータ値を更新する

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

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

### Before

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

### After

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

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

既存の値を持つキーを更新するには、キーを削除し、その値を新しいキーに渡します。たとえば、[Customer (顧客)](https://docs.stripe.com/api/customers.md) オブジェクトを更新して、その `"loyalty_program"` キーを[削除](https://docs.stripe.com/metadata.md#delete-single-key)し、キーの値 `"yes"` を新しい `"rewards_program"` キーに渡すことができます。

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

### Before

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

### After

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

## メタデータを削除する

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

### 1 つのキーを削除する

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

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

### Before

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

### After

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

### すべてのキーを削除する

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

#### curl

```bash
curl https://api.stripe.com/v1/customers/{{CUSTOMER_ID}}
  -u <<YOUR_SECRET_KEY>>
  -d "metadata"=""
```

### Before

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

### After

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

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

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

### 例外

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

| オブジェクトのマッピング                                                                                                                                                   | 説明                                                                                                                                                                                                                                                               |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [PaymentIntent](https://docs.stripe.com/api/payment_intents.md) から [Charge](https://docs.stripe.com/api/charges.md)                                            | PaymentIntent が Charge を作成すると、メタデータは 1 回限りのスナップショットで Charge にコピーされます。PaymentIntent のメタデータに対する更新は、Charge には適用されません。                                                                                                                                               |
| [Payment Link (決済用の URL リンク)](https://docs.stripe.com/api/payment_links/payment_links.md) → [Checkout セッション](https://docs.stripe.com/api/checkout/sessions.md) | Payment Link で Checkout セッションを作成すると、メタデータが 1 回限りのスナップショットで Checkout Session にコピーされます。 Payment Link のメタデータに対する更新は、Checkout Session には適用されません。                                                                                                                     |
| [Subscription (サブスクリプション)](https://docs.stripe.com/api/subscriptions.md) → [Invoice (請求書)](https://docs.stripe.com/api/invoices.md)                            | Subscription で Invoice が作成されると、メタデータが 1 回限りのスナップショットで Invoice オブジェクトの [parent.subscription_details.metadata](https://docs.stripe.com/api/invoices/object.md#invoice_object-parent-subscription_details-metadata) 属性にコピーされます。サブスクリプションのメタデータに対する更新は、請求書には適用されません。 |
| [サブスクリプション](https://docs.stripe.com/api/subscriptions.md) から [請求書の項目](https://docs.stripe.com/api/invoice-line-item/object.md) へ                               | 請求書の項目の [タイプ](https://docs.stripe.com/api/invoice-line-item/object.md#invoice_line_item_object-type) が `subscription` に設定されている場合、サブスクリプションの現在のメタデータが表示されます。                                                                                                      |

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

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

| オブジェクトのマッピング                                                                                                                                                                | 説明                                                                                                                                                                                        |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Checkout Session](https://docs.stripe.com/api/checkout/sessions.md) から [PaymentIntent](https://docs.stripe.com/api/payment_intents.md) へ                                   | [payment_intent_data.metadata](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-payment_intent_data-metadata) 属性で含めたデータは、基になる PaymentIntent のメタデータに保存されます。 |
| [Checkout セッション](https://docs.stripe.com/api/checkout/sessions.md) → [Subscription (サブスクリプション)](https://docs.stripe.com/api/subscriptions.md)                               | [subscription_data.metadata](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-subscription_data-metadata) 属性で含めたデータは、基になるサブスクリプションのメタデータに保存されます。           |
| [決済用リンク](https://docs.stripe.com/api/payment_links/payment_links.md)から [PaymentIntent](https://docs.stripe.com/api/payment_intents.md) へ                                    | [payment_intent_data.metadata](https://docs.stripe.com/api/payment-link/create.md#create_payment_link-payment_intent_data) 属性に含めるデータは、決済用リンクによって作成された各 PaymentIntent のメタデータに保存されます。       |
| [Payment Link (決済用の URL リンク)](https://docs.stripe.com/api/payment_links/payment_links.md) → [Subscription (サブスクリプション)](https://docs.stripe.com/api/subscriptions.md)        | [subscription_data.metadata](https://docs.stripe.com/api/payment-link/create.md#create_payment_link-subscription_data) 属性に含めるデータは、決済用リンクによって作成された各サブスクリプションのメタデータに保存されます。                 |
| [Price (価格)](https://docs.stripe.com/api/prices.md) → [Product (商品)](https://docs.stripe.com/api/products.md)                                                               | [product_data.metadata](https://docs.stripe.com/api/prices/create.md#create_price-product_data-metadata) 属性で含めたデータは、関連付けられた製品のメタデータに保存されます。                                               |
| [Subscription Schedule (サブスクリプションスケジュール)](https://docs.stripe.com/api/subscription_schedules.md) → [Subscription (サブスクリプション)](https://docs.stripe.com/api/subscriptions.md) | [phases.metadata](https://docs.stripe.com/api/subscription_schedules/create.md#create_subscription_schedule-phases-metadata) 属性で含めたデータは、フェーズの開始時に基になるサブスクリプションのメタデータに保存されます。              |
| [Quote (見積もり)](https://docs.stripe.com/api/quotes.md) → [Subscription (サブスクリプション)](https://docs.stripe.com/api/subscriptions.md)                                            | [subscription_data.metadata](https://docs.stripe.com/api/quotes/create.md#create_quote-subscription_data-metadata) 属性で含めたデータは、見積もりが承認されるとサブスクリプションのメタデータに保存されます。                          |

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

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

たとえば、顧客が [Checkout セッション](https://docs.stripe.com/api/checkout/sessions.md) を使用して購入したときにカート ID を含めるには、Checkout セッションの作成時にメタデータとして指定します。

```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_1MotwRLkdIwHu7ixYcPLm5uZ" \
  -d "line_items[0][quantity]=1" \
  -d "metadata[cart_id]=6943"
```

顧客が決済プロセスを完了すると、Stripe は Checkout Session オブジェクトのメタデータが含まれた [checkout.session.completed](https://docs.stripe.com/api/events/types.md#event_types-checkout.session.completed) イベントを Webhook エンドポイントに送信します。Webhookを設定してそのイベントをリッスンし、メタデータにアクセスしてデータを処理する際に使用できるようにする必要があります。

```json
{
  "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"
      },
      ...
    }
  },
  "livemode": false,
  "pending_webhooks": 0,
  "request": {
    "id": null,
    "idempotency_key": null
  },
  "type": "checkout.session.completed"
}
```

## メタデータを検索する

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

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

Radar でメタデータを使用して、不正利用の防止に役立つカスタムルールを作成します。詳しくは、[Radar のメタデータ属性](https://docs.stripe.com/radar/rules/reference.md#metadata-attributes)をご覧ください。