Shopify、GraphQL Admin APIに契約価格の価格調整履歴（audit trail）を追加

記事のサマリー（TL;DR）

GraphQL Admin APIのバージョン2026-10で、ProductVariantContextualPricingに新フィールドauditTrailが追加されました。
read_productsアクセススコープを持つアプリは、この新フィールドを使って、Shopifyが商品バリアントの契約価格（contextual price）に適用した調整を、適用順に確認できます。
既存のアプリがこの変更の影響を受けることはなく、新フィールドを利用するかどうかはアプリ側の選択に委ねられています。

利用条件

この機能を利用するには、以下の条件を満たす必要があります。

GraphQL Admin APIのバージョン2026-10以降を使用すること。
アプリがread_productsアクセススコープを持っていること。
2026-10より前のAPIバージョンを使用しているアプリは、この新フィールドをクエリできません。

詳細

何が変更されたか

新しいProductVariantContextualPricing.auditTrailフィールドは、PricingAuditTrailオブジェクトを返します。このオブジェクトのpriceAdjustmentsフィールドには、Shopifyが適用した順序どおりに調整内容が格納されます。

各AuditTrailAdjustmentには、以下の情報が含まれます。

type：Shopifyが適用した操作。AuditTrailAdjustmentTypeの値として、ADDITION（加算）、MULTIPLICATION（乗算）、REPLACEMENT（置換）のいずれかが返されます。
value：その操作で使用された値。
price：その調整を適用した後の価格。
label：調整内容を説明する、ローカライズされた人間が読める形式の説明文。

原文では、アプリはlabelを表示用テキストとして扱うべきであり、その値はローカライズされたり変更されたりする可能性があるため、パースしたり、安定した識別子として使用したりすべきではないと説明されています。

今回の価格調整履歴（pricing audit trail）の最初のリリースでは、商品バリアントの契約価格（product variant contextual pricing）のみがサポートされます。注文明細行（order line items）や下書き注文明細行（draft order line items）の調整履歴は含まれていません。

Shopifyが完全かつ正確な調整履歴を返せない場合、priceAdjustmentsは部分的な結果の代わりに空のリストを返します。

対象となるアプリ

この変更は、GraphQL Admin APIのバージョン2026-10以降を使用し、Shopifyが契約価格（contextual product variant price）をどのように計算したかを説明する必要があるアプリに適用されます。

read_productsアクセススコープを持つアプリは、ProductVariantContextualPricing.auditTrailをクエリできます。2026-10より前のAPIバージョンを使用しているアプリは、このフィールドをクエリできません。

既存のアプリは、新フィールドを自ら選択してクエリしない限り、この変更の影響を受けません。また、この変更によって既存のProductVariantContextualPricing.priceフィールドやProductVariantContextualPricing.compareAtPriceフィールドが変更されることはありません。

なぜ重要か

アプリは、契約価格を算出した計算過程を確認できるようになります。原文では、ERPやB2B連携において、この情報を価格リスト、通貨換算、税金、手数料、端数処理による調整内容の説明に利用できると述べられています。

ただし、この調整履歴は価格の計算過程を説明するものであり、Shopifyが選択したマーケット、カタログ、価格リストを特定するものではないとされています。

対応方法

既存のアプリに対する対応は不要です。価格調整履歴を利用するには、以下の手順が必要です。

GraphQL Admin APIのバージョン2026-10以降を使用する。
アプリがread_productsアクセススコープを持っていることを確認する。
契約価格のクエリにauditTrailおよびpriceAdjustmentsを追加する。
契約価格の調整がある商品バリアントを使ってクエリをテストする。

成功したレスポンスでは、該当する調整内容が計算順に返されます。priceAdjustmentsが空のリストである場合は、Shopifyがその価格について完全な公開可能な調整履歴を返さないことを意味します。