2022年8月に、Stripeの新しいAPIバージョン2022-08-01がリリースされました。
今回はStripe Checkout / Payment Linksに多くの変更が含まれています。
そのため、2022-08-01バージョンでの大きな変更の確認と、アップグレード時の注意点を、Checkoutにフォーカスして紹介します。
Checkoutでデフォルトの挙動が変更されたもの
Customerデータを、デフォルトでは作成しなくなります。
これまでのバージョンでは、一回切り・サブスクリプションを問わず明示的に指定しない場合、Customerを新規作成する挙動でした。
そのため、会員機能を持たないECサイトなどでは、customer_creation: 'if_required'を明示的に指定し、Customerデータを作成しない設定にする必要がありました。
const result = await stripe.checkout.sessions.create({
+ customer_creation: 'if_required',
success_url: 'http://localhost:3000',
cancel_url: 'http://localhost:3000',
mode: 'payment',
line_items: [{
price: 'price_1K7Wz6L6R1kGwUF4ePxqXXbL',
quantity: 1
}],
billing_address_collection: 'required'
})
バージョン2022-08-01からは、customer_creationのデフォルト値がif_requiredに変わります。
そのため、明示的にCustomerの作成または既存CustomerのIDを指定しない場合、1回きりの注文ではCustomerの代わりにゲスト顧客が作成されます。
「注文完了後に、会員登録を促すUIを用意しているECサイト」など、Checkoutで作成したCustomerデータを利用するシステムを構成している場合、APIのアップグレード前に、customer_creation: 'always'を明示的に設定しましょう。
const result = await stripe.checkout.sessions.create({
+ customer_creation: 'always',
...
「ゲスト顧客」の詳細については、こちらの記事もご覧ください。
パラメータ名の変更や、データの作成タイミングが変更されたもの
Checkoutのセッションを作成した時、Payment IntentおよびSetup Intentが作成されなくなります
これまでのAPIバージョンでは、Checkoutのセッションを作成したタイミングでPayment IntentやSetup Intentが作成されていました。
API2022-08-01からは、これらのIntentがCheckoutのセッションがcompleteするタイミングで生成されます。
そのため、顧客の注文操作が完了する前に、Payment IntentまたはSetup Intentをupdateするシステムを運用している場合は、APIアップグレード前に構成の変更が必要です。
line_itemsのドキュメント未記載パラメータが廃止されました。
Checkoutで注文・契約する商品を登録する際に、line_itemsにアドホックな商品・料金データを指定できます。
この際のパラメータで、APIバージョン2022-08-01より前のバージョンでは、ドキュメントに記載のない値が指定できました。
- line_items[amount]
- line_items[currency]
- line_items[name]
- line_items[description]
- line_items[images]
これらのパラメータは、APIバージョン2022-08-01にて廃止されています。
もし利用している場合は、line_items.price_dataにデータを移行させましょう。
await stripe.checkout.sessions.create({
success_url: 'http://localhost:3000',
cancel_url: 'http://localhost:3000',
mode: 'payment',
billing_address_collection: 'required',
line_items: [{
- amount: 100,
- currency: 'jpy',
- name: 'dummy product',
- description: 'dummy product description',
- images: ['https://example.com'],
+ price_data: {
+ unit_amount: 100,
+ currency: 'jpy',
+ product_data: {
+ name: 'dummy product',
+ description: 'dummy product description',
+ images: ['https://example.com']
+ }
+ },
quantity: 1
}]
})
subscription_dataにて、couponが利用できなくなります
サブスクリプションの申し込みページを作成する場合に、subscription_data.couponでクーポンを事前設定できました。
await stripe.checkout.sessions.create({
subscription_data: {
coupon: 'XXXX'
}
...
Promotion Code APIの登場などの関係で、APIバージョン2022-08-01ではdiscountを利用しての設定に変更する必要があります。
await stripe.checkout.sessions.create({
- subscription_data: {
- coupon: 'XXXX'
- },
+ discounts: [{
+ promotion_code: "xxxx"
+ }]
...
配送料金に関わるパラメータ名が、変更されました
Invoice（請求書）など、複数のAPIで配送料金の設定が可能です。
しかし、APIによってパラメータ名が異なっていたため、APIバージョン2022-08-01にて統一する変更が入ります。
-
shipping_ratesが廃止され、shipping_optionsを利用します -
shipping_rateはshipping_costに変更されました -
shippingはshipping_detailsに変更されます
変更内容の詳細や、Checkout以外の変更を確認する方法
Stripeではドキュメントサイトにて、APIバージョンごとの変更内容を紹介しています。
※現時点(2022/10)では英語のみです。
APIバージョン2020-08-27よりも古いバージョンを利用されている場合は、こちらのドキュメントで、影響のある変更がないかを確認しましょう。