Pattern Variables Reference

Pattern variables allow you to generate dynamic values for fields like SKU, Barcode, Title, Tags, Metafields, Vendor, and Product Type. Use them by enabling Use pattern in the action editor and inserting variables or product fields into your pattern.

Variables that mirror Shopify Liquid fields now call that out explicitly (for example, "Liquid: product.title") so it's easy to reuse data you already know from themes.

Pattern basics

A non-technical guide for merchants using the pattern editor UI.

When to use patterns

• You need unique SKUs, barcodes, or tags for every variant.
• You want to prepend/append text (e.g., brand → title).
• You're copying existing data (vendor, options, metafields) into another field.
• You're generating sequential numbers (PO numbers, batch IDs).
• You want to pull a product metafield value into another field.

Turn on pattern mode

1. In the job Action editor, pick a field that supports patterns (SKUs, Barcodes, Titles, Tags, Metafields, etc.).
2. For most fields, click Use pattern to switch the editor from "Set to value" into pattern mode.
   • Note: For Metafields, pattern insertion is available directly in the value input—no checkbox needed!
3. Choose what to insert:
   • Click Insert variable for operational/computed tokens (sequential numbers, variant options, prefixes/suffixes, etc.).
   • Click Insert product field for direct product data (title, vendor, type, tags, handle) or product metafield values.
4. Combine plain text + variables + product fields to build your pattern (e.g., SKU-[PRODUCT_PREFIX]{{METAFIELD:custom.sku_prefix}}).
5. Click Preview changes to see the before/after table for real products before running the job.

Quick recipes

Goal	Pattern	Before → After
Sequential SKUs per product	[PRODUCT_PREFIX][SEQUENTIAL]	SKU blank → ARTI1001, ARTI1002, ...
Append brand to titles	[PRODUCT_VENDOR] - [PRODUCT_TITLE]	Title = Classic Tee → ACME - Classic Tee
Option-based tags	[COLLECTION_PREFIX]-[VARIANT_OPTION1]	Tags lacked size → Adds SUMM-Small, SUMM-Medium
Barcode fallback	[PRODUCT_PREFIX]-[VARIANT_NUMBER_2]-[SEQUENTIAL]	No barcode → ARTI-01-1001
Copy metafield to title	[PRODUCT_TITLE] - {{METAFIELD:custom.subtitle}}	Title → Artisan Coffee - Premium Blend
SKU from metafield prefix	{{METAFIELD:custom.sku_prefix}}-[SEQUENTIAL]	SKU blank → PREM-1001, PREM-1002

Tips:

• Use regular text (hyphens, spaces) to keep results readable.
• Wrap literal brackets by doubling them ([[ or ]]) if you need actual brackets in the output.
• Set the Sequential base (defaults to 1001) if you need a different starting number.

---

Insert Variable vs Insert Product Field

When editing a pattern, you'll see two buttons:

Insert variable (computed/operational tokens)

These are tokens that compute values or provide numbering:

• Prefixes/Suffixes: [PRODUCT_PREFIX], [PRODUCT_SUFFIX], [VARIANT_SUFFIX], [COLLECTION_PREFIX]
• Numbering: [SEQUENTIAL], [PRODUCT_NUMBER], [VARIANT_INDEX], [VARIANT_NUMBER_2], [VARIANT_POSITION]
• Variant options: [VARIANT_OPTION1], [VARIANT_OPTION2], [VARIANT_OPTION3]
• Variant data: [VARIANT_SKU], [VARIANT_BARCODE]
• Product ID: [PRODUCT_ID_SHORT]

Insert product field (direct product data)

These are tokens that insert actual product data:

• Product fields: [PRODUCT_HANDLE], [PRODUCT_TITLE], [PRODUCT_TAGS], [PRODUCT_VENDOR], [PRODUCT_TYPE]
• Product metafields: {{METAFIELD:namespace.key}} — any synced product metafield

---

Product Metafields in Patterns

You can insert any synced product metafield value into your pattern using the double-brace syntax:

{{METAFIELD:namespace.key}}

For example:

• {{METAFIELD:custom.brand_code}} — inserts the value of the custom.brand_code metafield
• {{METAFIELD:my_fields.sku_prefix}} — inserts the value of my_fields.sku_prefix

How to insert a metafield

1. Click Insert product field next to your pattern input.
2. Under "Product metafields", search for your metafield by name or namespace.key.
3. Click to insert it into your pattern.

Examples

Goal	Pattern	Result
SKU from metafield + sequential	{{METAFIELD:custom.sku_prefix}}-[SEQUENTIAL]	PREM-1001, PREM-1002
Title with subtitle metafield	[PRODUCT_TITLE] - {{METAFIELD:custom.subtitle}}	Artisan Coffee - Premium Blend
Tag with category metafield	{{METAFIELD:custom.category}}-[VARIANT_OPTION1]	Apparel-Small
Barcode from metafield	{{METAFIELD:custom.barcode_prefix}}[SEQUENTIAL]	BAR1001, BAR1002

Note: If a metafield doesn't exist or has no value for a product, it will be replaced with an empty string.

---

Available Variables

This table is the full list of supported tokens you can insert via Insert variable and Insert product field.

Token	Category	What it inserts	Example output	Liquid equivalent / notes
[PRODUCT_PREFIX]	Computed	First 4 characters of the product handle/title, uppercase + alphanumeric (pads with X if shorter)	ARTI	Derived (not a Liquid field)
[PRODUCT_SUFFIX]	Computed	Last 4 characters of the product handle/title, uppercase + alphanumeric	FFEE	Derived (not a Liquid field)
[PRODUCT_ID_SHORT]	Computed	Last 4–6 digits of the product ID	123456	Derived from product GID
[VARIANT_POSITION]	Variant	Variant position as stored in Shopify (1-based). Can be non-contiguous if variants were deleted.	1	Not the same thing as [VARIANT_INDEX]
[VARIANT_INDEX]	Variant	Variant index, 1-based, zero-padded to 3 digits (reset per product)	001	Same underlying counter as [VARIANT_NUMBER_2], different padding
[VARIANT_NUMBER_2]	Variant	Variant index, 1-based, zero-padded to 2 digits (reset per product)	01	Same underlying counter as [VARIANT_INDEX], different padding
[VARIANT_OPTION1]	Variant	Option value 1 (e.g. Size/Color depending on your product)	Small	Direct variant data
[VARIANT_OPTION2]	Variant	Option value 2	Red	Direct variant data
[VARIANT_OPTION3]	Variant	Option value 3	Cotton	Direct variant data
[VARIANT_SUFFIX]	Computed	Last 3 characters of option 1, uppercase + alphanumeric	ALL	Derived from [VARIANT_OPTION1]
[VARIANT_SKU]	Variant	Current variant SKU	SKU-RED-SM	Liquid: variant.sku
[VARIANT_BARCODE]	Variant	Current variant barcode / GTIN	1234567890123	Liquid: variant.barcode
[SEQUENTIAL]	Numbering	Sequential number across the whole job (starts at base, defaults to 1001)	1001	Increments per targeted variant
[PRODUCT_NUMBER]	Numbering	Number derived from product index in the job (base + product index)	1001	Increments once per product (not per variant)
[COLLECTION_PREFIX]	Computed	First 4 characters of the first collection name, uppercase + alphanumeric	SUMM	Requires the product to belong to a collection
[PRODUCT_HANDLE]	Product field	Full product handle (URL slug)	artisan-coffee	Direct product data
[PRODUCT_TITLE]	Product field	Full product title	Artisan Coffee Beans	Liquid: product.title
[PRODUCT_TAGS]	Product field	All product tags joined by ,	coffee, beans	Liquid: product.tags (joined)
[PRODUCT_VENDOR]	Product field	Product vendor	Acme Roasters	Liquid: product.vendor
[PRODUCT_TYPE]	Product field	Product type	Coffee	Liquid: product.type
{{METAFIELD:namespace.key}}	Product metafield	Product metafield value for that namespace.key	PREM	Empty string if missing/unset; inserted via Insert product field

---

Where patterns & variables are supported

This table mirrors the in-app “Where patterns & variables are supported” table.

Action / field	Underlying field(s)	Patterns supported?	Notes & limitations
Title	Product title	Yes – enable “Use pattern” on the Title action.	Runs once per product. Best for product-level text (can still reference variant variables like [VARIANT_OPTION1]).
Description	Product description	Yes – enable “Use pattern” on the Description action.	Runs once per product. Long text is supported; preview may truncate very long results.
SEO Title	Product SEO title	Yes – via the SEO action when Field = SEO Title.	Product-level only. Patterns resolve once per product; use variant variables sparingly.
SEO Description	Product SEO description	Yes – via the SEO action when Field = SEO Description.	Product-level only. Multi-line text is supported; preview shows the resolved text.
Handle	Product handle	Yes – via the SEO action when Field = Handle.	Product-level only. Make sure the pattern resolves to a URL-safe string; invalid handles will be rejected by Shopify.
Vendor	Product vendor	Yes – enable “Use pattern” on the Vendor action.	Product-level only. Useful for combining vendor with other product/variant data (for example, [PRODUCT_VENDOR]-[VARIANT_SKU]).
Product type	Product product type	Yes – enable “Use pattern” on the Product type action.	Product-level only. Patterns must still resolve to a single product type string.
Tags	Product tags	Yes – enable “Use pattern” on the Tags action.	Product-level. Patterns generate tag strings; the app still treats the result as individual tags (comma-separated when not using patterns).
Metafields	Product metafields (namespace.key)	Yes – when mfOp = Set and “Use pattern” is enabled.	Patterns resolve to string values. You’re responsible for matching the metafield’s type (for example, not producing invalid JSON for JSON metafields).
Variant SKU	Variant SKU	Yes – enable “Use pattern” on the SKU action.	Runs per targeted variant (after Variant Filter & Selection). Supports [SEQUENTIAL], variant options, and product variables for structured SKUs.
Variant barcode	Variant barcode	Yes – enable “Use pattern” on the Barcode action.	Runs per targeted variant. Patterns must still resolve to valid barcode / GTIN values for your use case.
Price & compare-at price	Variant price and compare-at price	No – patterns are not supported.	Use the dedicated price operations (set, increase/decrease by amount or percent, rounding helpers) instead of patterns.
Collections	Product collection membership	No – patterns are not supported.	Collections are selected explicitly; you can’t dynamically generate collection handles with patterns.
Status	Product status	No – patterns are not supported.	Status is limited to Shopify’s allowed values (ACTIVE, DRAFT, ARCHIVED, UNLISTED).
Variant add / edit / delete / replace	Variant structure and core fields	No – patterns are not supported on these structural actions.	Use SKU/barcode/price actions with patterns for dynamic values; structural actions focus on which variants exist, not on patterning their fields.

---

Modifiers (advanced)

Some variables support simple modifiers inside the brackets:

• SKU before the first dash: [VARIANT_SKU|before:-]
• SKU after the first dash: [VARIANT_SKU|after:-]

If the delimiter isn’t found, the original value is used.

Product fields “as variables” (what this means)

When you click Insert product field, you are inserting direct product data into your pattern:

• Product fields like title/vendor/type/tags/handle (the [PRODUCT_…] tokens in the table above)
• Product metafields via the {{METAFIELD:namespace.key}} token (any synced definition)

These tokens are different from the computed/numbering tokens in Insert variable because they don’t generate a new value — they copy what’s already on the product (or metafield definition).

---

Potentially overlapping / redundant tokens (review)

None of the tokens are strict duplicates (each one can produce a different output or formatting), but a few are close enough that it’s worth calling them out:

• [VARIANT_INDEX] vs [VARIANT_NUMBER_2]: both refer to the 1-based variant index (reset per product). The difference is formatting (3 digits vs 2 digits). Keep both if merchants care about fixed-width formatting.
• [VARIANT_POSITION] vs [VARIANT_INDEX]: these often match, but aren’t guaranteed to. POSITION follows Shopify’s stored position; INDEX is the app’s per-product ordering counter.
• [SEQUENTIAL] vs [PRODUCT_NUMBER]: both start from the same base, but SEQUENTIAL increments per targeted variant while PRODUCT_NUMBER increments once per product. They solve different naming needs.
• [VARIANT_SUFFIX] vs [VARIANT_OPTION1]: SUFFIX is derived from option 1 but gives you a short, fixed-length uppercase token. It exists because patterns don’t support “substring” operations.

---

Liquid-equivalent variables

The following variables map directly to Shopify Liquid fields, making it easy to reuse naming patterns from themes or scripts:

Pattern variable	Liquid field	Notes
[PRODUCT_TITLE]	product.title	Complete product title
[PRODUCT_TAGS]	product.tags	Joined with ,
[PRODUCT_VENDOR]	product.vendor	Vendor / brand
[PRODUCT_TYPE]	product.type	Product type
[VARIANT_SKU]	variant.sku	Variant SKU
[VARIANT_BARCODE]	variant.barcode	Variant barcode

Look for the "Liquid: …" hint in the Insert variable menu inside the app. The FAQ now includes a "Patterns & variables" section that walks through concrete examples if you need a refresher.

Pattern Examples

SKU Patterns

• [PRODUCT_PREFIX][SEQUENTIAL] → ARTI1001, ARTI1002, ARTI1003
• [PRODUCT_PREFIX]-[VARIANT_OPTION1]-[VARIANT_NUMBER_2] → ARTI-Small-01, ARTI-Large-02
• SKU-[PRODUCT_ID_SHORT]-[VARIANT_INDEX] → SKU-123456-001, SKU-123456-002
• {{METAFIELD:custom.sku_prefix}}-[SEQUENTIAL] → PREM-1001, PREM-1002

Title Patterns

• [PRODUCT_HANDLE] - [VARIANT_OPTION1] → artisan-coffee - Small
• [PRODUCT_TITLE] ([VARIANT_OPTION1]) → Artisan Coffee Beans (Small)
• [PRODUCT_TITLE] - {{METAFIELD:custom.subtitle}} → Artisan Coffee - Premium Blend

Tag Patterns

• [COLLECTION_PREFIX]-[VARIANT_OPTION1] → SUMM-Small
• [PRODUCT_PREFIX]-[SEQUENTIAL] → ARTI-1001
• {{METAFIELD:custom.category}}-[VARIANT_OPTION1] → Apparel-Small

Sequential Base

The sequential base is the starting number for [SEQUENTIAL] and [PRODUCT_NUMBER]. By default it's 1001, but you can change it in any action that supports patterns. Example with base 5000:

• First variant processed → [SEQUENTIAL] = 5000
• Second variant → 5001

Pattern Validation

The app validates patterns and will show specific error messages if you use an invalid variable. It will also suggest similar valid variables (for example, typing [SEQUENCE] suggests [SEQUENTIAL]).

For metafield tokens, the app will show a warning if the referenced metafield definition hasn't been synced from Shopify.

Tips

• Use Insert variable for computed values like sequential numbers and prefixes.
• Use Insert product field for direct product data like title, vendor, and metafield values.
• Combine both in a single pattern to build rich, dynamic values.
• Use [PRODUCT_PREFIX] or [PRODUCT_HANDLE] to keep SKUs organized by product.
• Lean on [PRODUCT_TITLE], [PRODUCT_VENDOR], or [VARIANT_SKU] whenever you want parity with Shopify Liquid data.
• Use {{METAFIELD:namespace.key}} to pull metafield values into other fields.
• Preview your changes before creating the task to see how patterns resolve.

Was this helpful?

Need help building a pattern? Visit the Support & contact checklist for what to include (shop URL, job ID, pattern snippet, screenshots), then email support@xyppy.com or open an issue at GitHub Issues.