Admin GraphQL 2026-07: refunds/taxLines completeness and shipping field semantics

GraphQL Admin API Troubleshooting
1

Hello Shopify Developer Support,

We are building a read-only reporting integration for our store, Sushi Lab, using Admin GraphQL API version 2026-07.

Merchant Support referred us to Developer Support because the following questions remain unresolved. Please route this request to the team responsible for these API fields.

1. Completeness of Order.refunds and LineItem.taxLines

Merchant Support stated that these list fields do not accept first. However, the API reference lists an optional first argument for both fields, described as truncating the array:

Please confirm for version 2026-07:

  • When first is omitted, does each field return the complete list?
  • Are there any default or maximum server-side limits?
  • If a list can be truncated, how can an integration detect this and retrieve every element, given that these fields expose no after or pageInfo?

2. Does using Bulk Operations guarantee completeness of these lists?

Merchant Support recommended Bulk Operations. We understand that Bulk Operations handle pagination for connections, but our question concerns the nested list fields above.

For a successful bulk query containing orders → refunds and orders → lineItems → taxLines, with first omitted from the list fields:

  • Are all refunds and tax lines guaranteed to be included?
  • Do any list-specific limits still apply?
  • If completeness is not guaranteed, what supported retrieval method or independent count can we use to verify it?

Reference: Bulk Operations guide.

3. Conflicting meaning of totalShippingPriceSet

Merchant Support described the fields as follows:

  • totalShippingPriceSet: originally charged shipping amount.
  • currentShippingPriceSet: shipping amount remaining after refunds and discounts.
  • totalRefundedShippingSet: refunded shipping amount.

However, the API reference currently describes totalShippingPriceSet in terms of shipping costs returned to the customer, which appears to overlap with totalRefundedShippingSet.

Reference: Order shipping fields.

Please clarify:

  • What exactly does totalShippingPriceSet represent? Is the current documentation wording incorrect?
  • Is it calculated before or after shipping discounts?
  • Is it fixed at order creation, or can it change after order edits, shipping-line additions/removals, or refunds?
  • Does currentShippingPriceSet reflect all those changes?
  • How does taxesIncluded affect each of the three fields? In particular, does totalRefundedShippingSet include refunded shipping tax?
  • Is there a guaranteed relationship between these fields? If so, under which conditions does it hold?

A numerical example covering a shipping discount followed by a partial shipping refund, and clarification of what changes after an order edit, would help. Please distinguish tax-inclusive and tax-exclusive values.

We need version-specific API behavior to avoid silently missing records or counting shipping refunds twice. We are asking for clarification of the API contract, rather than debugging of our custom code.

Please provide documentation references or a written technical clarification applicable to version 2026-07. If any behavior is not guaranteed, please state that explicitly and identify the supported alternative.

Thank you,
Oleksii
Sushi Lab

2

Hi @Sushi_Lab, I checked this on a test store.

Both Order.refunds and LineItem.taxLines do accept an optional first argument, documented as “Truncate the array result to this size”, so the advice that they don’t accept first isn’t accurate. Neither field publishes a default or maximum, and with no cursor or pageInfo there’s no documented way to detect or page past truncation. On my 2026-07 test store, omitting first returned both lists in full, and first: 1 returned one entry each, though that may not hold at any list size.

The bulk operations guide covers connection fields, and nothing there promises these plain list fields come back complete in a bulk export.

The shipping fields don’t reconcile the way you might expect. Replacing a 10 EUR shipping line with 6 EUR via order edits moved totalShippingPriceSet to 16 while currentShippingPriceSet read 6 and totalRefundedShippingSet stayed 0, and two partial shipping refunds gave 10 / 6 / 4. So total minus refunded isn’t a reliable way to reconstruct current shipping. Use currentShippingPriceSet for what shipping costs now, tax-inclusive when order.taxesIncluded is true and pre-tax otherwise. The edit also created a refund record while refunded shipping stayed 0, so a refund record alone doesn’t mean shipping was refunded.

I’ve asked the team to confirm list limits, bulk behavior, and the shipping-field wording. What list sizes are you seeing on real orders?