Executive summary
- The metafieldsSet mutation in the Admin GraphQL API has moved from a flat 10 point cost to dynamic complexity costing, where the cost reflects how many distinct resources a call touches.
- Cost is now 10 points plus the weight of each distinct owner: Order 10, Product 4, ProductVariant 2, Collection, Customer and Shop 1 each, all other types 0.
- Affects any app or integration writing metafields at volume, particularly ERP, PIM and OMS connectors batching updates across many orders or products.
What changed
Previously every metafieldsSet call cost 10 points regardless of how many metafields or resources it touched. The cost is now 10 plus the sum, for each owner type, of the number of distinct owners multiplied by that type's weight. Each owner counts once per invocation no matter how many metafields you set on it, so writing ten metafields to one product costs the same as writing one. Because the mutation accepts at most 25 metafields, the ceiling for a single invocation is 260 points, reached by writing to 25 distinct orders.
One detail catches people out: cost is per invocation, not per request. If you use GraphQL aliases to send several metafieldsSet mutations in one request, each alias pays its own base 10 points and owners are not deduplicated. Three aliases updating the same 25 orders costs 780 points, not 260.
Why it matters
The rationale tells you how to optimize. A metafield write is not finished when the mutation returns. For every distinct resource whose metafields change, Shopify does background follow-up work: webhooks, cache invalidation, search reindexing and other per-owner processing. That work scales with resources touched, not metafields written. Flat pricing meant a request generating 25 times the downstream work cost the same as a trivial one, and bursts of high fan-out traffic have degraded metafield write performance for every store on the shared infrastructure.
For most Plus merchants the practical exposure is in the nightly sync. If your ERP integration writes a custom field to every order it imports, your point spend on that job just went up substantially, because Order carries the heaviest weight at 10. Product catalog syncs are cheaper at weight 4, and metaobject writes are free at weight 0. Worth measuring before you assume you are fine.
Role-specific impact
- Marketers: No direct effect, though tooling that stamps metafields onto large customer or product sets may run slower if it does not batch by owner.
- Developers: Group metafields by owner, since extra metafields on the same resource are free. Do not split a high fan-out call to reduce cost: every call pays the base 10 points, so 25 orders in 25 requests costs more in total. Read extensions.cost in the response, and send Shopify-GraphQL-Cost-Debug=1 for a per-field breakdown.
- Store admins: Expect integration vendors to ask about sync windows. If a nightly job starts throttling, the fix is on the vendor side, not in your store settings.
Use-case example
Real-world scenario
A wholesale merchant syncs order data to an ERP and writes back a single fulfillment reference metafield on each order. The connector batched 25 orders per mutation, which cost 10 points under the old model. It now costs 260 points, a 26 fold increase for the same work. Against a standard 2000 point bucket refilling at 100 points per second, a 5000 order backlog that used to clear in a few minutes now throttles repeatedly and stretches past the sync window. The fix is not to split the batch, which costs more, but to add proper backoff on THROTTLED and spread the job across a longer window.
Implementation checklist
- List every integration calling metafieldsSet, including middleware and internal jobs, not just installed apps.
- For each, record the owner types written and the number of distinct owners per call, then recompute cost with the new formula.
- Group writes so all metafields for one resource go in a single call, since extra metafields on the same owner are free.
- Audit any use of GraphQL aliases, which multiply the base cost and do not deduplicate owners.
- Instrument extensions.cost in responses so spend is logged rather than estimated.
- Confirm every caller handles THROTTLED with backoff and retry rather than failing the batch.
- Re-time nightly sync windows for the jobs that write order metafields, which carry the heaviest weight.
FAQ
Q: Should we split large batches into smaller requests to avoid throttling?
A: No. Every call pays the 10 point base, so splitting one 25 order call into 25 calls costs 500 points instead of 260. Keep the batch and handle throttling with backoff.
Q: Which writes are unaffected?
A: Owner types with weight zero, including metaobjects, cost the same as before. Single resource writes remain cheap, between 10 and 20 points.
Resources
Need guidance? Talk to Makro.