Executive summary
- What: ProductVariant gains a barcodes connection and a barcodes input on productSet, productVariantsBulkCreate, and productVariantsBulkUpdate. The single ProductVariant.barcode field is now deprecated.
- Why: A variant can hold up to 20 typed identifiers, so any integration reading one value may now be seeing a fraction of the record without knowing it.
- Who: App and integration developers syncing product identifiers to an ERP, OMS, POS, marketplace, or supplier feed.
What changed
Read a variant's full identifier set from the new barcodes connection, and write it with the barcodes input on productSet, productVariantsBulkCreate, and productVariantsBulkUpdate. Each barcode can declare a type of UPC, EAN, ISBN, GTIN, or ASIN, validated against that standard's character, length, prefix, and check-digit rules. Omit the type and the value is stored exactly as sent, so untyped data behaves as before.
The mechanics worth memorising: a variant accepts up to 20 barcodes of 255 characters each, the first one sent is what the legacy field returns and sorts first in the connection, a single input cannot set both barcode and barcodes, and sending barcodes replaces the entire set rather than appending. The barcode filter on products and productVariants queries now matches any barcode on a variant.
ProductVariant.barcode is deprecated but functional. Reading it returns the first entry in the connection, writing it updates that entry and leaves the rest untouched, and writing a blank value clears it and promotes the next code in the set. Shopify will announce a removal date separately, with a full API version of notice.
Why it matters
The deprecation notice is routine. The silent truncation risk is not, and it is the only part of this change that deserves engineering time this quarter.
Once a merchant adds a second barcode, an integration reading only barcode receives one value with no indication that others exist. There is no error, no warning, and no version bump involved. A catalog edit in the admin is enough for your sync to start representing an incomplete record. If that sync feeds an ERP, a marketplace listing, or a POS lookup, the downstream system now disagrees with Shopify about what identifies the product, and the disagreement stays invisible until a scan fails.
Note the ordering semantics too. Because position determines what the legacy field returns, a merchant reordering barcodes in the bulk editor changes what your integration reads without touching any code you own. Treat first position as a contract, not an implementation detail.
Role-specific impact
- Marketers: No direct impact, though marketplace feed mismatches traced to identifier drift now have a clearer root cause and a real fix.
- Developers: Move identifier reads to the barcodes connection, and remember that writing barcodes replaces the whole set. A partial write that omits existing codes will delete them.
- Store admins: Adding a second barcode in the admin is now a change with integration consequences. Coordinate with whoever owns your ERP or POS sync before rolling it out across a catalog.
Use-case example
Real-world scenario
A Plus merchant syncs identifiers nightly into NetSuite through a middleware job reading ProductVariant.barcode. Merchandising starts adding supplier UPCs as second barcodes so receiving can scan inbound cases. The job keeps reading the first value, the private-label EAN, and reports success every night. NetSuite never learns about the supplier codes, so roughly 8 percent of inbound receipts still fail to match and land in a manual queue. Neither system logs an error, because from the job's perspective nothing changed. Repointing the read at the barcodes connection resolves it in one sprint.
Implementation checklist
- Inventory every code path that reads ProductVariant.barcode, including middleware, scheduled jobs, and third-party apps you do not maintain.
- Repoint those reads at the barcodes connection and handle multiple values explicitly rather than taking the first and moving on.
- Audit writes for the replace-not-append behaviour, and make sure any barcodes input includes the codes you intend to keep.
- Never set both barcode and barcodes in the same variant input, since that is rejected.
- Decide whether to declare types. Validation is useful but will reject values your existing data may not satisfy, so test against real catalog data first.
- Agree with merchandising on what belongs in first position while any unmigrated consumers remain.
FAQ
Q: Is ProductVariant.barcode going away soon?
A: Not yet. It is deprecated but fully functional, with a removal date to be announced separately. The urgency comes from silent truncation, not the removal timeline.
Q: What happens if we send barcodes with only the new supplier code?
A: You delete the others. The barcodes input replaces the variant's entire set, so every write must include the full list you want to keep.
If you need help auditing an ERP or POS integration against this change, our team can scope the work.
Resources
ProductVariant, Admin GraphQL API 2026-10
Need guidance? Talk to Makro.