How to name your image files

Name each image after the identifier it belongs to, optionally followed by an underscore and a number for its position: <identifier>_<order>.<extension>.

The rule

The app turns a file name into a matching key in three steps:

1. Remove the extension: everything after the last ..
2. If the part after the last underscore is a number, that number is the image’s order and everything before it is the identifier. Otherwise the whole name is the identifier.
3. Lowercase the identifier. Matching is case-insensitive on both sides.

Examples

File name	Identifier used	Order	Notes
AB-1234.jpg	ab-1234	1st	Single image for the variant
AB-1234_0.jpg	ab-1234	1st	_0 and no suffix mean the same
AB-1234_1.jpg	ab-1234	2nd
AB-1234_2.png	ab-1234	3rd
7891234567890_1.jpg	7891234567890	2nd	Barcode/EAN matching
RED-SHIRT_M.jpg	red-shirt_m	1st	M is not a number, so it stays in the identifier
AB_12_3.jpg	ab_12	4th	Only the last segment is the order
AB-1234.v2.jpg	ab-1234.v2	1st	Only the text after the last dot is the extension
AB-1234	(empty)	none	Never matches. Files need an extension

Image order

Use the numeric suffix to control the gallery order:

AB-1234_0.jpg  →  1st image (also the variant image)
AB-1234_1.jpg  →  2nd image
AB-1234_2.jpg  →  3rd image

• Only the relative order matters. _1, _3, _7 gives the same order as _1, _2, _3.
• No suffix means first. AB-1234.jpg and AB-1234_0.jpg are equivalent, so don’t use both.
• The lowest number becomes the variant image. Give the main photo the lowest number.
• Without replace mode, new images are added after the product’s existing images.
• Order numbers above 999 are capped.

Do’s

• Keep identifiers exactly as they are in Shopify (case doesn’t matter, everything else does).
• Use _0, _1, _2… or _1, _2, _3… consistently.
• Use .jpg, .jpeg, .png, .webp or .gif.
• Keep file names unique inside the folder.

Don’ts

• Don’t add trailing spaces (AB-1234 .jpg). The space becomes part of the identifier. Values in Shopify are trimmed; file names are not.
• Don’t start a file name with an underscore (_AB-1234.jpg).
• Don’t upload files without an extension.
• Don’t use letters for ordering (AB-1234_a.jpg looks for ab-1234_a).
• Don’t mix conventions in one folder (some files with _1, others with -1).

When your file names don’t follow your SKUs

You don’t always have to rename thousands of files:

• Use a “contains” matching type when names carry extra text (see Matching options).
• Put your image code in a metafield and match on it.
• Use AI matching (beta) for inconsistent names.
• Ask us for identifier clean-up rules, for example to ignore everything after the first dash in a SKU.