Promo code triggers — wildcards, privacy & health

This is the deep companion to Using promo codes as triggers, which covers the basic add-a-code flow. This page documents the mechanics behind that flow, the advanced patterns it unlocks, and the edge cases that trip merchants up. It assumes you already know how to add a Promo Code rule to a condition, so it does not repeat the basic setup steps.

How the trigger matches under the hood

When you pick a discount code in a condition rule, the app does not store the code text on your rule. Instead it stores an internal promo code ID — a private reference that points to the code behind the scenes. The discount code text itself lives in a separate, app-side record that maps that ID back to the human-readable code.

At storefront runtime the flow is:

1. The shopper applies one or more discount codes to their cart.
2. The app's proxy resolves those applied codes back into the matching internal promo code IDs.
3. Your Promo Code rule matches against those resolved IDs — not against the raw code text.

This indirection has two practical consequences you can rely on:

• The same code can be reused across many conditions and campaigns. Each rule that references a code keeps its own internal ID, so reusing SUMMER20 in three different campaigns is completely safe — they do not collide or overwrite each other.
• Your trigger codes stay out of your page source. Because the rule stores an opaque ID and the matching happens on the server, the actual code text is never written into your storefront's HTML.

Every time you save a campaign that uses promo codes, the app re-syncs these mappings to match exactly what your rules currently say. You never manage the IDs yourself — you only ever pick the discount code by name.

Two matchers

The Promo Code rule supports two matchers. The matcher you choose decides whether one exact code fires the offer or a whole family of codes does.

Exact code (is equal to)

This is the default behavior most merchants want. The offer fires only when the shopper has applied the specific code you chose — SUMMER20 triggers, SUMMER21 does not.

Prefix wildcard (starts with)

With starts with, you provide a prefix and the offer fires for any applied code that shares it. For example, the prefix INFLUENCER matches:

• INFLUENCER_ALEX
• INFLUENCER_SAM
• INFLUENCER_2026

This is the right tool for code families you generate in bulk — one rule covers every code that shares the prefix, so you do not have to add a separate rule for each influencer or affiliate.

Behind the scenes, choosing starts with changes how the proxy resolves codes: instead of looking up only exact codes, it runs a prefix (regex) lookup on the server so that any applied code sharing the prefix resolves to your rule and fires the offer. You do not need to register the individual codes in the app — only the prefix.

Which campaign types support promo codes

The Promo Code data point is only available on three campaign types:

If you are editing a campaign of a different type and do not see Promo Code in the data-point list, that is expected — the selector is hidden on campaign types that do not support it. To use a promo code trigger, build it on a Gift with Purchase, Auto-Add, or Checkout Upsell campaign.

Privacy and timing

Promo-code triggers are designed so your codes stay private and your offers fire reliably — but the design also introduces a small delay you should plan for.

Your codes are never exposed

The code text is never written into your storefront's page source. Shoppers cannot read your trigger codes by inspecting the page, because the rule only ever carries the internal ID and the code-to-ID resolution happens on the app's server.

Expect a short round-trip delay

Promo conditions are evaluated on the app's server and proxy — not inside the storefront widget. After a shopper applies a code, there is a brief delay (about one request round trip) before the triggered offer appears while the app resolves the applied codes and re-evaluates the condition. This is normal and is not a sign of a misconfiguration.

Pre-checkout placement only

Keeping the trigger healthy

A promo-code trigger can only fire if the discount code it points to is still active in Shopify. The app continuously checks this and surfaces problems in two ways.

The campaign list health warning

The app validates the codes referenced by each active campaign against the Shopify Admin API. If a referenced code is no longer usable, a red health warning appears next to the campaign name in the campaign list, with the message:

The promo code {code} is inactive.

If several codes are inactive, they are all listed comma-separated in a single message — for example The promo code CODE1, CODE2 is inactive. — so a campaign that references several broken codes shows every one of them in that one line.

A disabled or deleted code means the campaign can no longer fire — shoppers who apply that code will not see the offer.

What the validator checks

When the app validates a code against the Shopify Admin API, it can report any of these problems:

How to fix an unhealthy trigger

For the full list of campaign health warnings and what each one means, see Campaign statuses, limits & health warnings.

Combining promo codes with other rules

A promo-code rule is just one rule inside a condition, so you can combine it with any other data point using AND / OR logic.

• AND a code with a subtotal or product rule to scope the gift — for example, "applied GIFT50 AND cart subtotal is greater than or equal to 50". The offer only fires when both are true.
• OR several codes together so that any one of them fires the same offer — useful when one promotion is run under multiple codes.

Recipes

Troubleshooting

The code is applied but the offer does not appear

Work through these in order:

Related