12月 20, 2025

Storefront APIが、不足または無効なギフトカード受取人詳細をカートに追加した際にエラーを返すようになりました

12月 20, 2025

Storefront APIがギフトカードの不正確な受取人詳細をエラーとして返すようになりました

1. 技術的課題の定義と現状分析

APIバージョン2026-01以降、Storefront APIは、ギフトカードを受取人の詳細が不正確または欠落しているカートに追加しようとすると、GIFT_CARD_RECIPIENT_INVALIDエラーを返すようになりました。それ以前は、cartCreateまたはcartLinesAddの変異を使用してカートにギフトカードを追加しようとした際に、受取人の詳細が無効（例えば、メールアドレスが欠落している場合）であると、空のカートと空のuserErrorsが返されていました。

2. 具体的な技術的ソリューションの提案

この変更により、cartCreateまたはcartLinesAddの変異に対しては、クライアントにギフトカード受取人のエラーを返すための情報がGIFT_CARD_RECIPIENT_INVALIDエラーとして返されます。これにより、ECサイトの開発者は、ユーザーがギフトカードをカートに追加する際に、受取人の詳細が正確に入力されているかどうかを正確に検証できるようになりました。

3. 実装手順とコード例

以下に、エラーハンドリングの実装手順とコード例を示します。

3.1 cartCreateの実装


mutation {
  cartCreate(input: {
    lines: [{ merchandiseId: "Z2lkOi8vc2hvcGlmeS9Qcm9kdWN0LzE=", quantity: 1, customAttributes: [{key: "recipientEmail", value: "invalid email"}]}]
  }) {
    cart {
      id
    }
    userErrors {
      field
      message
      code
    }
  }
}

3.2 cartLinesAddの実装


mutation {
  cartLinesAdd(cartId: "Z2lkOi8vc2hvcGlmeS9DYXJ0LzE=", lines: [{ merchandiseId: "Z2lkOi8vc2hvcGlmeS9Qcm9kdWN0LzE=", quantity: 1, customAttributes: [{key: "recipientEmail", value: "invalid email"}]}]) {
    cart {
      id
    }
    userErrors {
      field
      message
      code
    }
  }
}