# 検索

Stripe データ内でオブジェクトを検索します。

一部の上位の API リソースは、検索 API メソッドを使用した取得に対応しています。検索 API を使用すると、Stripe オブジェクトを柔軟に取得できます。検索は、すべてのリソースで[ページ分割](https://docs.stripe.com/api/pagination.md)を行うよりもスピーディーな方法です。検索クエリを作成するには、[検索クエリ言語](https://docs.stripe.com/search.md#search-query-language)を確認して、リソースのクエリフィールドを参照してください。

- [支払いのクエリフィールド](https://docs.stripe.com/search.md#query-fields-for-charges)
- [顧客のクエリフィールド](https://docs.stripe.com/search.md#query-fields-for-customers)
- [請求書のクエリフィールド](https://docs.stripe.com/search.md#query-fields-for-invoices)
- [PaymentIntents のクエリフィールド](https://docs.stripe.com/search.md#query-fields-for-paymentintents)
- [価格のクエリフィールド](https://docs.stripe.com/search.md#query-fields-for-prices)
- [商品のクエリフィールド](https://docs.stripe.com/search.md#query-fields-for-products)
- [サブスクリプションのクエリフィールド](https://docs.stripe.com/search.md#query-fields-for-subscriptions)

## 制限事項

### 最小 API バージョン

検索を使用するためにサポートされている最小の API バージョンは `2020-08-27` です。アップグレードについて、詳細は Stripe の [API アップグレードガイド](https://docs.stripe.com/upgrades.md)をご覧ください。アカウントの API バージョンをアップグレードせずに検索を使用するには、`Stripe-Version` リクエストヘッダーを設定して単一リクエストの API バージョンを上書きします。

```bash
-H "Stripe-Version: 2026-09-30.endive"
```

ライブラリを使用する際に API バージョンを上書きする方法については、[SDK](https://docs.stripe.com/sdks.md#versioning) のガイドをご覧ください。

### データの鮮度

データは即時に検索可能にならないため、read-after-write (書き込み後の読み取り) フローの検索 (支払い実行直後の検索など) は使用しないでください。通常の動作条件では、データは 1 分以内に検索可能になりますが、障害が発生した場合は、新しいデータや更新されたデータが反映されるまでに時間がかかることもあります。

データが即時に利用可能になる必要がある read-after-write (書き込み後の読み取り) フローでは、[請求書の一覧表示](https://docs.stripe.com/api/invoices/list.md)などの各種リストアップ API を使用してください。これらの API は、上で説明したデータ利用の遅延の影響を受けません。

### データの不一致

場合によっては、検索結果の検索に使用するデータが、受信した結果と一致しないことがあります。これは、Search API がキャッシュされたバージョンの PaymentIntent `status` を使用してフィルター処理しますが、最新バージョンの PaymentIntent に基づいてデータを返すために発生する可能性があります。

たとえば、ステータスが `requires_capture` の PaymentIntents を [Search Payment Intents API](https://docs.stripe.com/api/payment_intents/search.md) をクエリすると、ステータスが `succeeded` の PaymentIntents が返されることがあります。これは、Search API でキャッシュされた PaymentIntents のうち、ステータス `requires_capture` が古いものが見つかったものの、結果には現在の `succeeded` ステータスが返されるためです。

### レート制限

Stripe では、1 秒あたり最大 20 件の読み取り操作の[レート制限](https://docs.stripe.com/rate-limits.md)を、本番環境とテスト環境のすべての検索エンドポイントに適用しています。本番環境とテスト環境の制限は別々です。このレート制限を念頭に置くと、1 つ以上の API リソースに対して分析を実行する必要があるワークロードでは、[Sigma](https://docs.stripe.com/data/how-sigma-works.md) の方がはるかに効率的です。API リソースの大部分をエクスポートする必要があるワークロードでは、[Data Pipeline](https://docs.stripe.com/data/access-data-in-warehouse.md) の方が効率的です。

### 地域ごとの提供状況

インドに拠点を置く事業者は検索機能を利用できません。

### すべての結果のリストで省略されたテストクロックオブジェクト

Stripe のリスト API ([請求書の一覧](https://docs.stripe.com/api/invoices/list.md)など) では、すべてのリクエストを一覧表示するテストクロックで生成された結果が省略されます。これらのケースでテストクロックによって生成された結果を確認するには、`test_clock`、`customer`、または `subscription` など、特定の親内の結果をリクエストする必要があります。

たとえば、`GET /v1/invoices` はテストクロックで生成された請求書を返しませんが、`GET /v1/invoices/{customer_id}` は、テストクロックで生成されたものも含め、その顧客のすべての請求書を返します。

同様に、この例でテストクロック ID を指定して、そのテストクロックに関連するすべての請求書を取得することも、サブスクリプション ID を指定して、テストクロックによって生成された請求書を含む、そのサブスクリプションに対して請求されたすべての請求書を返すこともできます。

### ページ分割

まれに、結果セットをページ分割すると、一部のレコードの順序が変わり、ページ上で欠落や重複が発生することがあります。この問題が発生した場合は、[Stripe サポート](https://support.stripe.com)のフォームからお問い合わせください。

## 例

[Search charges API](https://docs.stripe.com/api/charges/search.md) と [Search Payment Intents API](https://docs.stripe.com/api/payment_intents/search.md) で実行できることの一例をご紹介します。

### 支払いメタデータで検索

カスタムメタデータの値に一致する支払いを検索します。

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

### 支払い last4 で検索

決済に使用されたカードの末尾 4 桁に一致する支払いを検索します。

```curl
curl -G https://api.stripe.com/v1/charges/search \
  -u "<<YOUR_SECRET_KEY>>:" \
  --data-urlencode "query=payment_method_details.card.last4:4242"
```

### 顧客のメールアドレスで検索

メールアドレスが一致する顧客を検索します。

```curl
curl -G https://api.stripe.com/v1/customers/search \
  -u "<<YOUR_SECRET_KEY>>:" \
  --data-urlencode "query=email:'sally@rocketrides.io'"
```

### 否定語フィルター

USD 通貨以外の PaymentIntents を検索します。

```curl
curl -G https://api.stripe.com/v1/payment_intents/search \
  -u "<<YOUR_SECRET_KEY>>:" \
  --data-urlencode "query=-currency:'usd'"
```

### 数値フィルター

`total` が 1000 を上回る請求書のオブジェクトをフィルターにかけます。

```curl
curl -G https://api.stripe.com/v1/invoices/search \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "query=total>1000"
```

### 複数のフィルターを組み合わせる

メタデータと通貨の組み合わせが一致する支払いを検索します。

```curl
curl -G https://api.stripe.com/v1/charges/search \
  -u "<<YOUR_SECRET_KEY>>:" \
  --data-urlencode "query=metadata['key']:'value' AND currency:'usd'"
```

## 検索クエリー言語

### クエリーの構造と用語

クエリ `clause` は、`field`、それに続く `operator`、それに続く `value` で構成されています。

|  |
| 句 | `email:"amy@rocketrides.io"` |
| フィールド | `email` |
| 演算子 | `:` |
| 値 | `amy@rocketrides.io` |

検索では、最大 10 個のクエリ句をスペースで区切るか、`AND` または `OR` キーワード (大文字と小文字は区別されません) を使用して組み合わせることができます。同じクエリで `AND` と `OR` を組み合わせることはできません。また、括弧を使用して特定の論理演算子を優先するオプションはありません。デフォルトでは、API によって句と `AND` ロジックが結合されます。

クエリ例 `email:"amy@rocketrides.io" metadata["key"]:"value"` は、メールアドレスが amy@rocketrides.io で、レコードのメタデータに `key` と `value` という値が含まれているレコードに一致します。

### 句に一致しないクエリを作成する

クエリの句は `-` 文字を使用して否定できます。たとえば、以下の検索では、メールアドレス `amy@rocketrides.io` に一致しないレコードが返されます。

`-email:"amy@rocketrides.io"`

### フィールドタイプ、部分文字列一致、数値コンパレーター

各検索フィールドでは、`:` による完全一致がサポートされます。`email` や `name` などの一部のフィールドでは部分文字列一致がサポートされます。`amount` などの一部のフィールドでは、`>` 、`<` などの数値コンパレーターがサポートされます。

各フィールドには、そのフィールドで使用できる操作を定義するタイプが含まれます。利用できるフィールドのリストについては、[リソースごとにサポートされているクエリフィールド](https://docs.stripe.com/search.md#supported-query-fields-for-each-resource)をご覧ください。

文字列に「より大きい」(`>`) などのサポートされていない演算子を使用すると、エラーが返されます。

| タイプ | 演算子 |
| --- | --- |
| トークン | 完全一致 (大文字小文字の区別なし) |
| 文字列 | 完全一致、部分文字列 (大文字小文字の区別なし)

文字列型の完全一致では、そのレコードにクエリのワードが同じ順序ですべて含まれているレコードが返されます。たとえば、クエリ `name:"one two three"` は、“one two three” という名前と、“one two three four” という名前の結果の両方と一致します。 |
| 数値 | 完全一致、次の値より大きい、次の値より小さい |

### 引用符

文字列の値は引用符で囲む必要があります。数値の場合、引用符はオプションになります。以下に例を示します。

- `currency:"usd"` は、引用符は必須であることを意味します。
- `payment_method_details.card.last4:1234` は、引用符はオプションであることを意味します。

引用符内の引用符はバックスラッシュ (`\`) でエスケープできます。

`description:"the story called \"The Sky and the Sea.\""`

### メタデータ

メタデータをサポートするオブジェクトに追加した[メタデータ](https://docs.stripe.com/api/metadata.md)を検索できます。

メタデータ検索では、形式 `metadata["<field>"]:"<value>"` を使用して句を構成します。

次の句は、寄付 ID「asdf-jkl」を含むレコードを照会する句 `metadata["donation-id"]:"asdf-jkl"`の作成方法を示しています。

オブジェクト上のメタデータキーの存在に対するクエリを実行できます。次の句は、`donation-id` がメタデータキーであるすべてのレコードに一致します。`-metadata["donation-id"]:null`

### 検索の構文

以下の表は、クエリーの構築に使用できる構文の一覧です。

| 構文 | 使用方法 | 説明 | 例 |
| --- | --- | --- | --- |
| `:` | `field:value` | 完全一致演算子 (大文字小文字の区別なし) | `currency:"eur"` では通貨が 「EUR」と完全に一致するレコードが返されます (大文字小文字は区別されません) |
| `AND`、`and` | `field:value1 AND field:value2` | このクエリーでは、両方の句に一致するレコードのみが返されます (大文字と小文字は区別されません) | `status:"active" AND amount:500` |
| `OR`、`or` | `field:value1 OR field:value2` | このクエリーでは、句のいずれかと一致するレコードが返されます (大文字と小文字は区別されません) | `currency:"usd" OR currency:"eur"` |
| `-` | `-field:value` | 句と一致しないレコードが返されます | `-currency:"jpy"` では、JPY 以外のレコードが返されます |
| `NULL`、`null` | `field:null` | フィールドプレゼンスのために使用される特別なトークン (大文字小文字の区別なし) | `url:null` では、URL フィールドが空のレコードが返されます |
| `\` | `" \"\""` | 引用符内の引用符をエスケープ | `description:"the story called \"The Sky and the Sea.\""` |
| `~` | `field~value` | サブストリング一致演算子 (サブストリングは 3 文字以上で指定してください) | `email~"amy"` は、amy@rocketrides.io および xamy と一致するものが返されます |
| `>`、`<`、`=` | - `field<value`
- `field>value`
- `field>=value`
- `field<=value` | より大きい/より小さい演算子 | `amount>"10"` では、金額が 10 以上のオブジェクトが抽出されます |

## リソースごとにサポートされているクエリフィールド

### 支払いのクエリフィールド

| フィールド | 使用状況 | タイプ (トークン、文字列、数値) |
| --- | --- | --- |
| 金額 | `amount>1000` | 数値 |
| billing_details.address.postal_code | `billing_details.address.postal_code:12345` | トークン |
| 作成日 | `created>1620310503` | 数値 |
| 通貨 | `currency:"usd"` | トークン |
| 顧客 | `customer:"cus_123"` | トークン |
| disputed | `disputed:"true"` | トークン |
| メタデータ | `metadata["key"]:"value"` | トークン |
| payment_method_details.{{SOURCE}}.last4 | `payment_method_details.card.last4:1234` | トークン |
| payment_method_details.{{SOURCE}}.exp_month | `payment_method_details.card_present.exp_month:12` | トークン |
| payment_method_details.{{SOURCE}}.exp_year | `payment_method_details.interac_present.exp_year:2022` | トークン |
| payment_method_details.{{SOURCE}}.brand | `payment_method_details.card.brand:"visa"` | トークン |
| payment_method_details.{{SOURCE}}.fingerprint | `payment_method_details.card.fingerprint:"fp"` | トークン |
| payment_method_details.{{SOURCE}}.reader | `payment_method_details.card_present.reader:"tmr_FDOt2wlRZEdpd7"` | トークン |
| payment_method_details.{{SOURCE}}.location | `payment_method_details.interac_present.location:"tml_FBakXQG8bQk4Mm"` | トークン |
| refunded | `refunded:"true"` | トークン |
| ステータス | `status:"succeeded"` | トークン |

`SOURCE` の場合は、`card`、`card_present`、`interac_present`、または [Terminal が対応しているその他の支払い方法](https://docs.stripe.com/terminal/payments/additional-payment-methods.md)を使用します。オンライン支払いの場合は `card` を使用し、Interac ネットワークの Terminal カード提示支払いの場合は `interac_present` を使用し、その他の Terminal カード提示支払いの場合は `card_present` を使用します。

`reader` や `location` など、カードに固有ではない Terminal 関連のフィールドをクエリする場合、`wechat_pay` などの他の決済手段を使用することもできます。

`disputed` フィールドは、不審請求の申請の存在に関する「true」と「false」のトークンのみを受け入れます。

`refunded:"true"` は全額返金された支払いをフィルタリングし、`refunded:"false"` はまったく返金されていない、または部分的に返金された支払いをフィルタリングし、`refunded:null` は返金されていない支払いをフィルタリングします。

### 顧客のクエリフィールド

| フィールド | 使用状況 | タイプ (トークン、文字列、数値) |
| --- | --- | --- |
| 作成日 | `created>1620310503` | 数値 |
| メールアドレス | `email~"amyt"` | 文字列 |
| メタデータ | `metadata["key"]:"value"` | トークン |
| 名前 | `name~"amy"` | 文字列 |
| 電話 | `phone:"+19999999999"` | 文字列 |

### 請求書のクエリフィールド

| フィールド | 使用状況 | タイプ (トークン、文字列、数値) |
| --- | --- | --- |
| 作成日 | `created>1620310503` | 数値 |
| 通貨 | `currency:"usd"` | トークン |
| 顧客 | `customer:"cus_123"` | トークン |
| last_finalization_error_code | `last_finalization_error_code:"customer_tax_location_invalid"` | トークン |
| last_finalization_error_type | `last_finalization_error_type:"invalid_request_error"` | トークン |
| メタデータ | `metadata["key"]:"value"` | トークン |
| 番号 | `number:"MYSHOP-123"` | 文字列 |
| receipt_number | `receipt_number:"RECEIPT-123"` | 文字列 |
| ステータス | `status:"open"` | 文字列 |
| サブスクリプション | `subscription:"SUBS-123"` | 文字列 |
| 合計 | `total>1000` | 数値 |

### PaymentIntents のクエリフィールド

| フィールド | 使用状況 | タイプ (トークン、文字列、数値) |
| --- | --- | --- |
| 金額 | `amount>1000` | 数値 |
| 作成日 | `created>1620310503` | 数値 |
| 通貨 | `currency:"usd"` | トークン |
| 顧客 | `customer:"cus_123"` | トークン |
| メタデータ | `metadata["key"]:"value"` | トークン |
| ステータス | `status:"succeeded"` | トークン |

### 価格のクエリフィールド

| フィールド | 使用状況 | タイプ (トークン、文字列、数値) |
| --- | --- | --- |
| 有効 | `active:"true"` | トークン |
| 通貨 | `currency:"usd"` | トークン |
| lookup_key | `lookup_key:"standard_monthly"` | 文字列 |
| メタデータ | `metadata["key"]:"value"` | トークン |
| 商品 | `product:"prod_123"` | 文字列 |
| タイプ | `type:"recurring"` | トークン |

### 商品のクエリフィールド

| フィールド | 使用状況 | タイプ (トークン、文字列、数値) |
| --- | --- | --- |
| 有効 | `active:"true"` | トークン |
| 説明 | `description~"t-shirts"` | 文字列 |
| メタデータ | `metadata["key"]:"value"` | トークン |
| 名前 | `name~"amy"` | 文字列 |
| 配送可能 | `shippable:"true"` | トークン |
| url | `url~"/dinosaur_swag"` | 文字列 |

### サブスクリプションのクエリフィールド

| フィールド | 使用状況 | タイプ (トークン、文字列、数値) |
| --- | --- | --- |
| 作成日 | `created>1620310503` | 数値 |
| メタデータ | `metadata["key"]:"value"` | トークン |
| ステータス | `status:"active"` | トークン |
| canceled_at | `canceled_at>1721521117` | 数値 |