検索

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

一部の上位の API リソースは、検索 API メソッドを使用した取得に対応しています。検索 API を使用すると、Stripe オブジェクトを柔軟に取得できます。検索は、すべてのリソースでページ分割を行うよりもスピーディーな方法です。検索クエリを作成するには、検索クエリ言語を確認して、リソースのクエリフィールドを参照してください。

制限事項

最小 API バージョン

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

Command Line

-H "Stripe-Version: 2025-02-24.acacia"

ライブラリを使用する際に API バージョンを上書きする方法については、SDK のガイドをご覧ください。

データの鮮度

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

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

データの不一致

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

たとえば、ステータスが requires_capture の PaymentIntents を Search Payment Intents API をクエリすると、ステータスが succeeded の PaymentIntents が返されることがあります。これは、Search API でキャッシュされた PaymentIntents のうち、ステータス requires_capture が古いものが見つかったものの、結果には現在の succeeded ステータスが返されるためです。

レート制限

毎秒最大 20 回の読み取り操作のレート制限が本番環境とテスト環境のすべての検索エンドポイントに適用されます。本番環境とテスト環境の制限は個別にかかります本番環境とテスト環境の制限は個別にかかります。レート制限がかかることを考慮すると、1 つ以上の API リソースによる分析が伴う作業では、Sigma の方がはるかに効率的です。API リソースの大部分をエクスポートする必要がある作業では、Data Pipeline プロダクトの方が効率的です。

地域ごとの提供状況

検索は、インドの加盟店にはお使いいただけません。

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

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

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

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

例

Search charges API と Search PaymentIntents API で実行できることの例をいくつか紹介します。

支払いメタデータで検索

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

支払い last4 で検索

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

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

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

否定語フィルター

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

数値フィルター

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

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

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

検索クエリー言語

クエリーの構造と用語

クエリ 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 などの一部のフィールドでは、> 、< などの数値コンパレーターがサポートされます。

各フィールドには、そのフィールドで使用できる操作を定義するタイプが含まれます。利用できるフィールドのリストについては、リソースごとにサポートされているクエリフィールドをご覧ください。

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

タイプ演算子

トークン完全一致 (大文字小文字の区別なし)

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

文字列

完全一致、部分文字列 (大文字小文字の区別なし)

文字列型の完全一致では、そのレコードにクエリのワードが同じ順序ですべて含まれているレコードが返されます。たとえば、クエリ 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.\""

メタデータ

メタデータをサポートするオブジェクトに追加したメタデータを検索できます。

メタデータ検索では、形式 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"`	トークン
refunded	`refunded:"true"`	トークン
ステータス	`status:"succeeded"`	トークン

SOURCE の場合は、card、card_present、interac_present を使用します。オンライン支払いの場合は card を使用して、Interac ネットワークの Terminal カード提示支払いの場合は interac_present を使用し、その他の Terminal カード提示支払いの場合は card_present を使用します。

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`	数値