検索

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

• 支払いのクエリフィールド
• 顧客のクエリフィールド
• 請求書のクエリフィールド
• PaymentIntents のクエリフィールド
• 価格のクエリフィールド
• 商品のクエリフィールド
• サブスクリプションのクエリフィールド

制限事項

最小 API バージョン

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

-H "Stripe-Version: 2025-04-30.basil"

ライブラリを使用する際に 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 で実行できることの例をいくつか紹介します。

支払いメタデータで検索

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

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

支払い last4 で検索

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

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

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

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

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

否定語フィルター

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

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

数値フィルター

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

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

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

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

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

検索クエリー言語

クエリーの構造と用語

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

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

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

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

引用符

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

• 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

検索の構文

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

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

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

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

reader や location など、カード固有ではない Terminal 関連のフィールドを照会する場合は、wechat_pay のような他の支払い方法も使用できます。

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

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

顧客のクエリフィールド

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

PaymentIntents のクエリフィールド

価格のクエリフィールド

商品のクエリフィールド

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