Stripe APIをバージョン: 2022-08-01にアップグレードする前に、確認しておきたいポイント[Checkout編]

2022年8月に、Stripeの新しいAPIバージョン`2022-08-01`がリリースされました。

今回はStripe Checkout / Payment Linksに多くの変更が含まれています。

そのため、`2022-08-01`バージョンでの大きな変更の確認と、アップグレード時の注意点を、Checkoutにフォーカスして紹介します。

## Checkoutでデフォルトの挙動が変更されたもの

### Customerデータを、デフォルトでは作成しなくなります。

これまでのバージョンでは、一回切り・サブスクリプションを問わず**明示的に指定しない場合、Customerを新規作成する**挙動でした。

そのため、会員機能を持たないECサイトなどでは、`customer_creation: 'if_required'`を明示的に指定し、Customerデータを作成しない設定にする必要がありました。

```diff_javascript
    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の代わりに**ゲスト顧客**が作成されます。

https://support.stripe.com/questions/guest-customer-faq

「注文完了後に、会員登録を促すUIを用意しているECサイト」など、**Checkoutで作成したCustomerデータを利用するシステム**を構成している場合、APIのアップグレード前に、`customer_creation: 'always'`を明示的に設定しましょう。


```diff_javascript
    const result = await stripe.checkout.sessions.create({
+     customer_creation: 'always',
...
```

「ゲスト顧客」の詳細については、こちらの記事もご覧ください。

https://qiita.com/hideokamoto/items/783cd6fef5759aaf1505

https://qiita.com/hideokamoto/items/654d0ae3146aad839a11

## パラメータ名の変更や、データの作成タイミングが変更されたもの

### Checkoutのセッションを作成した時、Payment IntentおよびSetup Intentが作成されなくなります

これまでのAPIバージョンでは、**Checkoutのセッションを作成したタイミング**でPayment IntentやSetup Intentが作成されていました。

API`2022-08-01`からは、これらのIntentが**Checkoutのセッションがcompleteするタイミング**で生成されます。

そのため、**顧客の注文操作が完了する前**に、Payment IntentまたはSetup Intentをupdateするシステムを運用している場合は、APIアップグレード前に構成の変更が必要です。

### `line_items`のドキュメント未記載パラメータが廃止されました。

Checkoutで注文・契約する商品を登録する際に、`line_items`にアドホックな商品・料金データを指定できます。

https://qiita.com/hideokamoto/items/6bd31422e2ebb27d4eaa

この際のパラメータで、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`にデータを移行させましょう。

```diff_javascript
    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`でクーポンを事前設定できました。

```js
await stripe.checkout.sessions.create({
  subscription_data: {
    coupon: 'XXXX'
  }
...
```

Promotion Code APIの登場などの関係で、APIバージョン`2022-08-01`では`discount`を利用しての設定に変更する必要があります。

```diff_javascript
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`に変更されます

https://qiita.com/hideokamoto/items/1a56ede321e1650a6302

## 変更内容の詳細や、Checkout以外の変更を確認する方法

Stripeではドキュメントサイトにて、APIバージョンごとの変更内容を紹介しています。

https://stripe.com/docs/upgrades#2022-08-01

※現時点(2022/10)では英語のみです。

APIバージョン`2020-08-27`**よりも古いバージョン**を利用されている場合は、こちらのドキュメントで、影響のある変更がないかを確認しましょう。