商品一覧やサービスのプラン表など、Stripeに登録した価格データを一覧表示させたいケースは少なくありません。
そしてStripeでは、表示させたい価格データを絞り込み・検索する方法がいくつか用意されています。

今回はその方法のうち、「検索キー（Lookup Key）」を利用する方法について紹介します。

検索キーとは？

検索キーは、StripeのPrice APIの機能の１つです。
Stripeに登録した価格データをより検索しやすく、また価格の変更を反映しやすくするために作られました。

以下のコードサンプルのように、Price APIのListで特定の検索キーを持つ価格データだけを取得することができます。

const result = await stripe.prices.list({
  lookup_keys: ['membership_free', 'membership_bronze', 'membership_silver']
})

検索キーを価格に登録する

検索キーは、APIから登録することができます。
登録済みの価格に設定する場合は、update APIを利用しましょう。

await stripe.prices.update('price_xxxx', {
  lookup_key: 'monthly_membership_bronze',
})

新しく登録する価格に設定する場合は、create APIを利用します。

await stripe.prices.create({
  product: 'prod_xxxx',
  nickname: 'Monthly Membership (Silver)',
  currency: 'jpy',
  unit_amount: 2000,
  lookup_key: 'monthly_membership_silver',
  recurring: {
    interval: 'month'
  }
})

一度登録した検索キーは、Stripe Dashboardの価格詳細ページからも確認できます。

「検索キー」はアカウント全体でユニーク

同じ「検索キー」を異なる価格に設定することはできません。
設定しようとすると、以下のようなエラーが発生しますのでご注意ください。

    A price (`price_xxxx`) already uses that lookup key.

検索キーを使って検索する

検索キーの設定が終われば、あとはList APIで検索するだけです。

const result = await stripe.prices.list({
  lookup_keys: ['membership_free', 'membership_bronze', 'membership_silver']
})

配列で設定した検索キーと一致する価格データを、一覧で取得することができます。
また、以下のようにほかのList API引数と併用することも可能です。

const result = await stripe.prices.list({
  recurring: { interval: 'year' },
  active: true,
  lookup_keys: ['membership_free', 'membership_bronze', 'membership_silver']
})

Product IDでの検索との違い

価格データの絞り込み取得には、商品（Product）のIDを利用することもできます。
こちらの場合は、指定した商品に関連付けられている価格だけ取得できます。

const result = await stripe.prices.list({
  product: 'prod_xxx'
})

「商品に関連する価格データを一覧取得したい場合」は商品IDで検索することをお勧めします。
一方で、「異なる商品に紐づいている価格データを、個別に指定して一覧取得したい場合」は検索キーを利用しましょう。

対応するデータがない場合の振る舞い

APIで指定した検索キーを持つ価格が存在しない場合、APIは空の配列を返してきます。

{ "object": "list", "data": [], "has_more": false, "url": "/v1/prices" }

`transfer_lookup_key`を利用して、価格改訂に対応する

検索キーを利用するメリットはもう１つあります。それは「価格改訂時、価格データ取得側の実装を変える必要がなくなること」です。
検索キーを利用した検索の場合、設定した検索キーを別の価格に割り当て直すことができます。
そのために利用する引数が、transfer_lookup_keyです。

通常、すでに利用している検索キーをほかの価格に設定しようとすると、エラーが発生します。
しかしtransfer_lookup_keyを併用することで、検索キーを別の価格に移動させることができます。

/**
 * 新しい価格を作成し、検索キーの割り当て先も変更する
 **/
await stripe.prices.create({
  product: 'prod_xxxx',
  nickname: 'Monthly Membership (Silver)',
  currency: 'jpy',
  unit_amount: 3000,
+  transfer_lookup_key: true,
  lookup_key: 'monthly_membership_silver',
  recurring: {
    interval: 'month'
  }
})

/**
 * 作成済みの価格に、検索キーの割り当て先を変更する
 **/
await stripe.prices.update('price_xxxx', {
+  transfer_lookup_key: true,
  lookup_key: 'monthly_membership_bronze',
})

この操作を行うことで、検索キーを利用して価格データを取得している処理側のコードを変更することなく、新しい価格データをAPIやフロントエンドに表示させることができます。

まとめ

検索キーを利用することで、取得したい任意の価格データをまとめて取得できるようになります。
また、検索キーを割り当てる価格データを変更することで、新しい価格体系に変更する際に実装を変更する箇所を減らすこともできます。

REST APIだけでなく、Next.jsやGatsbyなどの静的サイトジェネレーターでも利用できるかと思いますので、ぜひお試しください。

参考記事

[PR] Stripe開発者向け情報をQiitaにて配信中！

2021年12月よりQiitaにて、Stripe開発者のためのブログ記事更新を開始しました。

[Stripe Updates]：開発者向けStripeアップデート紹介・解説
ユースケース別のStripe製品や実装サンプルの紹介
Stripeと外部サービス・OSSとの連携方法やTipsの紹介
初心者向けのチュートリアル(予定)

など、Stripeを利用してオンラインビジネスを始める方法について随時更新してまいります。

-> Stripe Organizationsをフォローして最新情報をQiitaで受け取る