税金計算用アプリがカートラインのプロパティを受け取れるようになりました

技術的課題の定義

ShopifyのAPIバージョン2026-01まで、税金計算用パートナーアプリはカートライン項目のプロパティを含むリクエストを送信できませんでした。これにより、各ライン項目に商人が追加したカスタム名前-値ペアのプロパティを取得することができませんでした。

現状の技術スタックと問題分析

これまでのAPIでは、税金計算リクエストを送信する際にカートライン項目のプロパティを含めることができませんでした。そのため、各ライン項目に追加されたカスタム名前-値ペアのプロパティ情報を取得するためには、別途処理を行う必要がありました。

技術的ソリューションの提案

APIバージョン2026-01より、税金計算用パートナーアプリはカートライン項目のプロパティを含むリクエストを送信できるようになりました。これにより、商人が各ライン項目に追加したカスタム名前-値ペアのプロパティを取得できるようになります。

実装手順とコード例

この機能を使用するためには、商人がカートライン項目に設定するプロパティ（例："token", "personalization", "gift_wrap"）と、パートナーアプリが受け取りたいプロパティキーを設定する必要があります。ただし、パートナーアプリが受け取れるプロパティキーは最大5つまでです。

設定例：

{
  "delivery_groups": [{
    "cart_lines": [
      {
        "id": "gid://shopify/CartLine/7",
        "quantity": 1,
        "merchandise": {
          "id": "gid://shopify/ProductVariant/456",
          "title": "Custom T-Shirt"
        },
        "cost": {
          "amount_per_quantity": {
            "currency_code": "USD",
            "amount": "25.00"
          }
        },
        "properties": {
          "token": "abc-123",
          "personalization": "John Smith"
        }
      },
      {
        "id": "gid://shopify/CartLine/6",
        "quantity": 2,
        "merchandise": {
          "id": "gid://shopify/ProductVariant/789",
          "title": "Custom Mug"
        },
        "cost": {
          "amount_per_quantity": {
            "currency_code": "USD",
            "amount": "15.00"
          }
        },
        "properties": {
          "token": "def-456",
          "personalization": "Jane Doe"
        }
      }
    ]
  }]
}

パフォーマンス・コスト分析

この変更により、各ライン項目に追加されたプロパティ情報を取得するための別途の処理が不要になり、サーバーのリソースを節約することができます。また、リクエストのレスポンス時間も短縮され、ユーザー体験の向上にも寄与します。

実装時の注意点・ベストプラクティス

パートナーアプリが受け取れるプロパティキーは最大5つまでなので、どのキーを選択するかは慎重に決定する必要があります。また、プロパティキーの選択は全ライン項目で共有されるため、各ライン項目で必要なプロパティを取得できるように設定することが重要です。

次のステップ・発展案

今後は、パートナーアプリが受け取れるプロパティキーの数を増やすことで、さらに詳細な情報を取得できるようにすることも考えられます。また、個々のライン項目に対するプロパティの設定も可能になると、より柔軟な設定が可能になります。

参考記事: Tax Partner Apps Can Now Receive Cart Line Properties in Tax Calculation Requests