Executive summary
- What: ProductVariantContextualPricing gains an auditTrail field in Admin API 2026-10, returning each adjustment Shopify applied to reach a contextual price, in order.
- Why: Price questions on B2B and international catalogues currently end in manual reconstruction. This turns the calculation into something you can read back.
- Who: Shopify Plus merchants running B2B price lists or multi-currency catalogues, and the ERP, CPQ, and support tooling built around them.
What changed
auditTrail returns a PricingAuditTrail object whose priceAdjustments field lists AuditTrailAdjustment entries in application order. Each entry carries four things: type, which is ADDITION, MULTIPLICATION, or REPLACEMENT; value, the number the operation used; price, the running result after that step; and label, a localized human-readable description.
Treat label as display text only. Shopify states plainly that it can be localized or reworded, so parsing it or keying off it will break. The field requires the read_products access scope and exists only on 2026-10 or later.
Two boundaries are worth noting. This first release covers product variant contextual pricing and does not extend to order or draft order line items. And if Shopify cannot produce a complete and correct trail, priceAdjustments returns an empty list rather than a partial one, so an empty array means no answer available, not a price with no adjustments.
Why it matters
On an enterprise B2B catalogue, a single contextual price can be the product of a price list percentage, a currency conversion, a rounding rule, and a fee, applied in an order that is not obvious from the admin. When a buyer questions a price today, the support path usually means someone reconstructing the arithmetic by hand against the B2B price list and payment terms configuration. That is slow, and it is not reliably repeatable.
A machine-readable trail changes the shape of that work. Support tooling can show the derivation next to the price. ERP reconciliation can assert that the price it received matches the adjustments Shopify reports, not just the final number. One caveat sets expectations correctly: the trail explains the calculation, not the selection. It will not tell you which market, catalogue, or price list Shopify chose in the first place.
Role-specific impact
- Marketers: Promotional and tiered pricing becomes easier to validate before launch, because you can confirm the stacking order rather than inferring it from spot checks.
- Developers: Add auditTrail and priceAdjustments to contextual pricing queries, render label as opaque text, and branch on an empty priceAdjustments list as an explicit unknown state.
- Store admins: Expect faster answers to buyer pricing questions once support tooling surfaces the trail. The underlying price fields are unchanged, so nothing you have configured needs revisiting.
Use-case example
Real-world scenario
An industrial distributor sells to 600 wholesale accounts across four currencies, with account-level price lists layered over a base catalogue. Pricing questions reached the support desk roughly 40 times a month, and each took a representative about 25 minutes to escalate, reconstruct, and answer. Surfacing the audit trail in the internal account view lets the representative read the derivation directly. Even partial deflection recovers most of a working day each month, and it removes the quieter risk of a representative explaining the price incorrectly.
Implementation checklist
- Confirm the app or integration holds the read_products access scope.
- Move the relevant queries to GraphQL Admin API version 2026-10 or later.
- Add auditTrail with priceAdjustments, requesting type, value, price, and label.
- Test against a variant that carries real adjustments rather than a base-price variant, so you see a populated trail.
- Render label as display text and never parse it or use it as an identifier.
- Handle an empty priceAdjustments list as an unavailable trail, not as a price without adjustments.
- Avoid planning work around order or draft order line item trails, which this release does not cover.
FAQ
Q: Does adding this field change any prices?
A: No. ProductVariantContextualPricing.price and compareAtPrice are untouched. The audit trail is read-only and purely additive, and existing apps are unaffected unless they query it.
Q: Can the trail tell us which price list applied?
A: No. It explains the sequence of adjustments, not the selection of the market, catalogue, or price list that produced them. You still need the context you passed in to answer that.
Resources
PricingAuditTrail object reference
Need guidance? Talk to Makro.