DEV Community

FlareCanary
FlareCanary

Posted on

Shopify Changed heldBy From a String to an Object in 2025-01 — Your Query Still Returns 200 OK

#shopify #api #graphql #monitoring

Shopify ships a new GraphQL Admin API version every quarter. Most releases are additive. A few are not. The 2025-01 release is one of the "are not": it removed a handful of fields that thousands of apps were reading, and it quietly changed the type of one of the most common fulfillment fields from a string to an object.

The endpoint still returns 200 OK. The query still parses. The field your code reads just isn't there anymore — or it's there under a new name with a completely different shape.

If you upgraded a Shopify app from 2024-x to 2025-01 without reading the full release notes and you're seeing "this field is empty now" in production, this is probably why.

The heldBy → heldByApp Change

On a FulfillmentHold object, the 2024-x GraphQL schema returned:

{
  fulfillmentHold {
    heldBy  # String! — "PrepSupport" or "ShopifyFulfillmentNetwork" or an app name
  }
}
Enter fullscreen mode Exit fullscreen mode

As of 2025-01, heldBy is gone. In its place:

{
  fulfillmentHold {
    heldByApp {
      title    # String! — "PrepSupport"
      id       # ID!
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

The 2025-01 release notes put it like this:

If you currently query fulfillmentHold.heldBy, then transition to querying fulfillmentHold.heldByApp.title.

The important thing is what happens if you don't. GraphQL in this version will happily return null for a field it no longer recognizes (depending on your client's error handling), or it will throw a field-level error that your resolver swallows. Your downstream code — the logic that routes held orders to a human, the Slack notification that names the blocking app, the dashboard tile that shows "held by X" — starts quietly producing empty strings or "Unknown."

Type systems don't save you here, either. Most Shopify SDKs are either hand-rolled TypeScript types generated from the schema at some pinned version, or they're any-shaped because the developer didn't codegen against the current version. If your schema snapshot is from 2024-10, heldBy is still in your types, your IDE still autocompletes it, and your unit tests (mocking your own types) pass. The mismatch only shows up at runtime, against Shopify's live API.

PrivateMetafield Is Just Gone

The second big removal in 2025-01:

PrivateMetafield is removed from the public GraphQL Admin API. Use app-data metafields instead.

There is no field rename, no transitional alias, no "deprecated for N versions" wind-down. Every query, mutation, and resolver that referenced PrivateMetafield, privateMetafields, privateMetafieldUpsert, or the MetafieldStorefrontVisibility object stops working.

If your app was using private metafields to store per-shop configuration — credentials, feature flags, per-merchant routing rules — that configuration didn't move anywhere. You have to migrate it to app-data metafields yourself, re-grant access via the new app-reserved namespace scheme, and replace every read and write. And until you do, the queries come back empty.

The reason this is a silent-failure story and not a loud one is that GraphQL errors on unknown types usually manifest as empty result sets plus a "errors": [...] array in the response body. Plenty of client libraries treat empty results as a valid zero-length response and log the error array at debug level. Your code reads data.app.privateMetafields.edges, gets [], and moves on. The merchant's configuration just looks like it was never set.

accountNumber and routingNumber, Also Gone

A smaller but spicier one, buried in the same release:

Removed accountNumber and routingNumber fields from ShopifyPaymentsBankAccount.

If your app was reading bank account details from Shopify Payments — for displaying masked account info, for reconciling payouts against external bookkeeping, for compliance paperwork — those two fields no longer exist. The field resolver returns null. Whatever UI or report depended on them now shows blanks.

The reason Shopify gave is reasonable (PCI / financial-data exposure narrowing). The reason apps break anyway is that nothing in the upgrade path forces you to notice. You bump your API version header from 2024-10 to 2025-01, you ship, and the fields that used to come back populated just come back null. Everything else is identical.

Why CI Tests and Type Systems Don't Catch This

Every time I write up one of these stories — the GitHub PushEvent commits field, Stripe's Basil current_period_end move, now Shopify 2025-01 — the pattern is the same:

  1. The upstream API version is under the upstream's control, not yours.
  2. The breaking change is a field removal or a type reshape, not a new 4xx status.
  3. Responses still parse. HTTP still returns success.
  4. Your unit tests pass because you mocked the response shape yourself.
  5. Your integration tests pass because your sandbox data was seeded before the change.
  6. Your type checker passes because your types were generated against the old schema.
  7. The break shows up in production, against real data, after a deploy that looked clean.

There is no test you can write inside your codebase that catches a response-shape change introduced by code you don't own. The contract is between two systems and you only control one of them.

What Actually Catches It

Three things can catch a silent upstream schema change, in order of cost:

1. Version pinning with forced upgrade cadence. Shopify lets you pin your API version via the Shopify-Api-Version header. Pin an explicit version and don't let it float. Then schedule the upgrade (2024-10 → 2025-01, etc.) as a deliberate project with a review of the full release notes, a grep of your codebase for removed/renamed fields, and a regression test against a non-production shop. This is what every Shopify app developer should already be doing. Most aren't, which is why forum posts like "Submit for review button is disabled after upgrading to 2025-04" keep showing up.

2. Deprecation-warning monitoring. Shopify exposes deprecated API call counts in the Partner Dashboard and will block app submissions if you have any in the 3-day window before review. Read the warnings, fix the calls. This requires that you bothered to upgrade in the first place, though — it doesn't catch drift on a version you've been sitting on.

3. Runtime shape monitoring. Poll the endpoints your app actually hits on a schedule, record the response shape, and alert when a field disappears, a type shifts, or nullability changes. This is the one catch for APIs that change shape out from under you without you bumping any versions — and it's the one that works for every third-party API, not just the ones that publish a deprecation dashboard. (FlareCanary does this; so do a few others. The point is to have something doing it, not specifically us.)

The economics matter. The cost of an undetected Shopify field rename isn't "an exception in the logs." It's usually something worse — wrong data on a merchant-facing dashboard, a fulfillment routing rule that silently misfires, a compliance report with a missing column. The business cost of one of those is larger than the annual cost of any monitor. And it only takes one.

The Next Shopify Release Is Already Doing This Again

Shopify's 2026-07 release (still months away as of this writing) is dropping grams from DraftOrderLineItem in favor of weight. customerPaymentMethodRemoteCreditCardCreate is fully removed after January 2026. These are the ones listed in the changelog; history says there will be 5–10 more smaller ones by the time the version actually ships.

If you integrate with Shopify, now is a good time to:

  • Grep your codebase for heldBy (without the App), privateMetafield, accountNumber, routingNumber, grams, multiLocation, customerPaymentMethodRemoteCreditCardCreate, metafieldDelete, visibleToStorefrontApi. Anything that comes back is a candidate break.
  • Pin your Shopify-Api-Version header explicitly if you aren't already.
  • Subscribe to the Shopify changelog and actually read it.
  • Set up shape monitoring on your most critical queries — fulfillment, orders, metafields, payments. Whether you do it yourself, use an observability tool, or use a schema-drift monitor, the cost of not doing it compounds every quarter.

Upstream API breaking changes are not a problem you can solve once. They're a recurring cost of running a product that depends on APIs you don't own. The apps that survive long-term aren't the ones that never get hit — they're the ones that notice within minutes instead of weeks.

I'm Wilson — I write about how third-party API schemas break, quietly, against apps that depend on them. If you integrate with Shopify, Stripe, GitHub, Twilio, or any of a dozen others, FlareCanary polls your critical endpoints and alerts on shape changes before your customers notice. Free tier. No card required.

Top comments (0)