Skip to main content
Back to changelog

Variants now support multiple barcodes

Merchants often sell the same variant under more than one identifier: a manufacturer UPC alongside a private-label EAN, a GTIN, a reissued ISBN, or an ASIN for a marketplace listing. Until now a variant held a single barcode value, so the extras ended up in metafields, tags, or outside Shopify entirely.

What's new

You can now read a variant's full set from the new barcodes connection on ProductVariant, and write it with the barcodes input on the productSet mutation, productVariantsBulkCreate mutation, and productVariantsBulkUpdate mutation.

Each barcode can declare a type: UPC, EAN, ISBN, GTIN, or ASIN. We validate the value against that standard's character, length, prefix, and check-digit rules. If you don't declare a type, we store the value exactly as you sent it, so untyped data keeps working as before.

Usage guidance

  • A variant accepts up to 20 barcodes, each up to 255 characters.
  • The first barcode you send is what the existing barcode field returns, and it sorts first in the barcodes connection.
  • A single variant input can't set both barcode and barcodes.
  • Sending barcodes replaces the variant's entire set, so include the barcodes you want to keep.
  • The barcode filter on the products and productVariants queries now matches any barcode on a variant.
  • Sending a barcode with a type will be validated against that standard's rules. If you don't declare a type, we store the value exactly as you sent it.

Compatibility with ProductVariant.barcode

ProductVariant.barcode is now deprecated, but nothing breaks today and barcode keeps working:

  • Reading barcode returns the first entry in the barcodes connection.
  • Writing barcode updates the first barcode in the barcodes connection and leaves the variant's other barcodes untouched. Sending a blank value clears the first barcode and replaces it with the next barcode in the set until there are no barcodes remaining.
  • A single variant input can't set both barcode and barcodes.

Adding or changing a barcode in the first position of the connection lets you keep control over surfaces you haven't migrated yet while still getting the full multiple barcode experience.

Be aware of potential silent truncation

Once a second barcode is added to a variant, an integration reading only barcode sees one of them with no signal that others exist. If your app syncs product identifiers to an ERP, a marketplace, a POS, or a supplier feed, move those reads to the barcodes connection.

We'll announce a removal date in a future post, with a full API version of notice before the field goes away.

To get started, refer to ProductVariant, ProductVariantBarcode, BarcodeInput, and BarcodeType.

Was this page helpful?