Executive summary
- What: GraphQL Admin API version 2026-10 introduces a feeDetails query that returns each specialized fee charged to a shop as a discrete FeeDetails object.
- Why: fee data that previously had to be read in aggregate can now be retrieved per transaction, with tax and settlement currency broken out.
- Who: finance and operations teams reconciling Shopify Payments against an ERP or accounting ledger, and the developers who maintain that integration.
What changed
The GraphQL Admin API now exposes feeDetails, a connection of FeeDetails nodes. Each node carries the fee name and amount, the flatRate and variableRate components that produce that amount, the taxAmount applied, the settlementAmount with the settlementCurrencyRate used to convert it, the associated orderTransaction where one exists, and createdAt plus processedAt timestamps.
The change is purely additive. No existing field changes shape or meaning, and no existing app needs modification. A shop with no recorded fees returns an empty connection rather than an error, so the query is safe to call unconditionally. Access requires the read_billing scope and API version 2026-10 or later.
Why it matters
Fee reconciliation is one of the quieter sources of month-end friction on Shopify Plus. Teams working from payout-level totals get a single blended figure with no way to attribute a variance to a specific order, so a discrepancy of a few hundred dollars turns into a manual hunt through payout reports.
Reading fees per transaction removes that guesswork. Because each FeeDetails node links back to its orderTransaction, you can attribute cost to the order that generated it and post a fee line at the same grain your finance team already works in. The split between flatRate and variableRate matters for cross-border businesses, where conversion and card-type surcharges sit inside what otherwise looks like one processing fee. settlementAmount and settlementCurrencyRate let you tie the Shopify figure to what actually reached the bank, which is where most reconciliation breaks surface.
Role-specific impact
- Marketers: minimal direct impact, though accurate per-order fee data improves contribution margin reporting and makes channel profitability comparisons more defensible.
- Developers: one additive query to adopt. Confirm read_billing is granted, move the integration to 2026-10, and page the connection like any other. No migration work is forced on you.
- Store admins: expect finance to ask for fee data at the order level once it is available. Decide where those lines land in your accounting system before the data starts flowing.
Use-case example
Real-world scenario
A Plus merchant selling into the United States and the European Union closes each month with a payout-to-bank variance of roughly 0.4 percent of processed volume. The finance team has written it off as a rounding artefact for two years. After moving their middleware to 2026-10 and pulling feeDetails alongside each order transaction, they find the variance concentrated in cross-border card fees carrying a variableRate component their flat-fee model never accounted for. The model gets corrected once, and the monthly manual adjustment, previously about three hours of analyst time, disappears.
Implementation checklist
- Confirm your app or middleware is pinned to GraphQL Admin API version 2026-10 or later.
- Verify the read_billing access scope is granted, and request it if it is not.
- Query feeDetails and select only the fields your ledger consumes, starting with feeName, amount, taxAmount, settlementAmount, and orderTransaction.
- Treat an empty connection as a valid result, not a failure state.
- Backfill a single closed month first and reconcile it against the payout report before trusting the pipeline.
- Map each fee type to a general ledger account with your finance team, and document the mapping in your ERP integration runbook.
FAQ
Q: Does this break our existing Shopify Payments reporting?
A: No. The change is additive and alters no existing field. Apps on earlier API versions, and apps that do not read Shopify Payments fees, are unaffected.
Q: Do we still need payout-level data if we have feeDetails?
A: Yes. Payout records remain the authoritative view of what Shopify deposited. feeDetails explains the composition of those deposits, so the two are complementary rather than interchangeable.
Resources
Need guidance? Talk to Makro.