1月 02, 2026

返品理由定義APIの新機能 - より詳細な返品情報を得るためのツール

1月 02, 2026

より詳細な返品理由を取得するための新API：Return Reason Definitions API

Shopify Plusでは、より詳細な返品理由を取得し、分析に活用できるようにする新しいAPIを導入しました。これにより、返品理由の分析をより細かく行うことが可能になり、顧客に対する返品体験をより最適化することができます。

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

以前のReturnReason enumは、返品理由を取得するためのデータモデルとして機能していました。しかし、このモデルでは、返品理由の詳細性に欠け、分析の精度を上げるのが難しいという問題がありました。

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

新たに導入されたReturnReasonDefinitionタイプは、より詳細な返品理由を取得することを可能にします。このタイプはid、handle、nameのフィールドを持ち、handleはプログラムのロジックで使用されます。

全ての返品理由を取得するためのreturnReasonDefinitionsクエリや、商品カテゴリに応じた返品理由を提供するsuggestedReturnReasonDefinitions接続、そして返品を作成するためのreturnCreate、returnRequest、orderRequestReturnミューテーションが新たに追加され、これらはreturnReasonDefinitionIdを引数として受け入れます。

実装手順とコード例

新APIの導入にあたり、アプリケーションが返品を作成する場合、ミューテーションをreturnReasonDefinitionIdを使用するように更新する必要があります。以下はその一例です。

mutation {
  returnRequest(input: {
    clientMutationId: "some client mutation id",
    id: "gid://shopify/ReturnRequest/1",
    lineItems: [{
      id: "gid://shopify/ReturnRequestLineItem/1",
      returnReasonDefinitionId: "gid://shopify/ReturnReasonDefinition/1"
    }]
  }) {
    returnRequest {
      id
    }
    userErrors {
      field
      message
    }
  }
}

また、LineItemに対するsuggestedReturnReasonDefinitionsクエリを使用して、各商品に対して文脈に適した返品理由を取得することが可能です。

query {
  lineItem(id: "gid://shopify/LineItem/1") {
    suggestedReturnReasonDefinitions {
      nodes {
        id
        handle
        name
      }
    }
  }
}