Shopify’s 2026-10 release brings a powerful new capability to the GraphQL Admin API: the feeDetails query. For developers building billing‑aware apps, this addition means you can now pull line‑item fee data—right down to tax, settlement currency, and the originating order transaction—rather than working with a single aggregated amount. In this post we’ll break down what changed, who needs to pay attention, and exactly how to start using feeDetails in your apps.
What Changed
The new feeDetails field returns a connection of FeeDetails objects. Each object surfaces a rich set of properties:
feeName – Human‑readable name of the fee (e.g., "Processing fee").amount – Monetary value of the fee, with currency code.flatRate and variableRate – The fixed component and the percentage component that compose the fee.taxAmount – Any tax levied on the fee.settlementAmount and settlementCurrencyRate – The fee expressed in the settlement currency and the FX rate used for conversion.orderTransaction – A reference to the OrderTransaction the fee is tied to (if applicable).createdAt and processedAt – Timestamps for when the fee was recorded and when it was settled.The addition is purely additive—no existing fields were altered—so current queries continue to work unchanged.
Who Is Affected
Developers building apps that rely on the GraphQL Admin API version 2026-10 or later and need visibility into Shopify Payments fees.Merchants indirectly benefit because apps can now surface fee breakdowns in dashboards, invoices, or custom reporting tools.If your app still targets an older API version or never reads billing data, you can ignore this change. Stores with no recorded fees will simply receive an empty connection, not an error.
Why It Matters
Previously, apps could only fetch a summed fee amount via the Billing API, which made it hard to reconcile individual transactions, attribute taxes, or build granular profit‑margin reports. With feeDetails you can:
Match fees to specific orders – Identify exactly which order generated a processing fee.Display tax breakdowns – Show merchants the tax component of each fee, improving financial transparency.Handle multi‑currency settlements – Use settlementAmount and settlementCurrencyRate to report fees in the currency actually settled with the bank.Build custom analytics – Combine feeDetails with order data to calculate true net revenue per channel, product, or campaign.How to Implement feeDetails
Upgrade to API version 2026-10 or later – Either set the version in your GraphQL request header or update your app’s API version settings in the Partner Dashboard.Add the read_billing scope – feeDetails is protected by the read_billing access scope. Ensure your OAuth flow requests it and that merchants approve.Query the fields you need – Below is a minimal query that pulls the most commonly used properties.graphql
query GetShopFeeDetails($first:Int = 20) {
shop {
feeDetails(first: $first) {
edges {
node {
feeName
amount {
amount
currencyCode
}
flatRate
variableRate
taxAmount {
amount
currencyCode
}
settlementAmount {
amount
currencyCode
}
settlementCurrencyRate
orderTransaction {
id
name
}
createdAt
processedAt
}
}
}
}
}
Handle empty results gracefully – If a shop has never incurred a Shopify Payments fee, the feeDetails connection will be empty. Your UI should display a friendly “No fees recorded” message rather than an error.Cache responsibly – Fee data can change when settlements occur, so treat it as mutable. A short‑term cache (e.g., 5‑10 minutes) is sufficient for most reporting dashboards.Best Practices & Next Steps
Validate currency conversions – Use settlementCurrencyRate to recalculate the fee in the merchant’s base currency if you need a unified view.Combine with OrderTransaction queries – Pull additional order details (line items, discounts) in the same request to build a complete financial picture.Monitor API deprecations – Although feeDetails is additive today, keep an eye on future version notes to ensure continued compatibility.Conclusion & Call to Action
The feeDetails query turns a previously opaque fee total into a transparent, itemized ledger. By upgrading to the 2026-10 GraphQL version and adding the read_billing scope, you can immediately start delivering richer financial insights to your merchant clients.
Ready to level up your app’s billing intelligence? Update your API version, test the query in Shopify’s GraphiQL Explorer, and roll out the new fee breakdown feature to your merchants today.
