Promo codes: triggers vs code-based discounts
Untangle the three ways promo codes appear in the app, set up code-based tier and shipping discounts, and read validation errors.
The phrase "promo code" means three different things in Llama Upsells, and mixing them up is the most common source of confusion. Sometimes a code is a trigger that gates a campaign, sometimes it is a Shopify discount the app creates for shoppers to enter, and sometimes it is just a plain coupon you made yourself. This page sorts out which is which, then walks through the code-based discounts the app can build for you and how applied codes are validated at the storefront.
The three meanings of "promo code"
When you read "promo code" in the app or in these docs, it is always one of the following. They look similar but behave very differently — most importantly, only one of them actually applies a discount.
| Meaning | Who creates it | What it does | Where the shopper enters it |
|---|---|---|---|
| Promo-code trigger (condition) | You reference an existing code; the app stores a mapping | Gates a campaign — fires an offer when a matching code is applied. Never discounts on its own. | The shopper applies the code at the cart; the app reacts to it |
Code-based app discount (CODE-type tier or shipping discount) | The app creates a real Shopify discount code for you | Unlocks the discount itself — buy-more-save-more pricing or free/discounted shipping | The shopper enters the code to unlock the discount |
| Plain Shopify discount code | You, directly in Shopify Admin | A normal coupon, with no special connection to the app | At the cart or checkout, like any Shopify code |
The single most important distinction: a trigger reacts to a code but applies no money off, while a code-based app discount is the discount. If you want a code that gives a price break, you need the second kind, not the first.
When it is a trigger
The promo-code trigger is the Applied discount codes condition you add to a campaign. It checks the codes a shopper has applied to their cart and, when one matches, lets the campaign's offer fire. It does not generate or apply any discount — you create the discount code in Shopify first, then reference it in the condition. This is fully documented in /docs/guides/targeting/promo-code-triggers; the rest of this page focuses on the other two meanings.
When it is a code-based app discount
Tier discounts and shipping discounts can each be set to a code type. In that mode the app creates a genuine Shopify discount code that the shopper types in to unlock the offer. These are covered in the next two sections.
When it is a plain Shopify code
A coupon you built yourself in Shopify Admin has no link to the app at all — until you point a promo-code trigger at it. On its own it behaves like any other Shopify discount.
Code-based tier discounts
A tier (buy-more-save-more) discount has a type of either Automatic or Code. The type controls how the discount is delivered, not what it discounts.
| Type | Behavior | Shopper effort |
|---|---|---|
| Automatic | The app creates a Shopify automatic discount. Qualifying carts get the price break with no action. | None — applies silently at checkout |
| Code | The app creates a Shopify code discount backed by the same tier logic. The shopper must enter the code to unlock the tiered pricing. | Must enter the code at the cart or checkout |
With the Code type, the app builds the discount in Shopify for you — you do not create the code yourself in Shopify Admin. The buy-more-save-more thresholds you configure (see /docs/guides/discounts/tier-discounts) only take effect once the shopper applies the code.
When to use Code vs Automatic
- Use Automatic when you want every qualifying cart to save without friction — the default "spend more, save more" experience.
- Use Code when the saving should be gated: a code you hand to influencers, email subscribers, or VIPs so only people who have the code get the volume pricing.
Code-type settings
Choose the Code type
When creating or editing the tier discount, set its type to Code. The app will generate a Shopify code discount instead of an automatic one.
Set the discount code text
Enter the code shoppers will type — for example BULK20 or VIP10. This is the literal text the shopper applies at the cart.
Decide once-per-customer
Turn on applies once per customer if each shopper should only be able to redeem the code a single time. Leave it off to allow repeat redemptions.
Set the active window
Set a start date for when the code becomes valid. Optionally set an end date; leave the end date empty to keep the code active indefinitely.
Because the tier pricing only applies after the code is entered, a shopper who never enters the code sees no discount at all — even if their cart clears every threshold. If you expected automatic savings, you chose the wrong type. Switch to Automatic.
Code-based shipping discounts
Shipping discounts follow the same pattern. A shipping discount's type is either Automatic or Code.
| Type | Behavior |
|---|---|
| Automatic | The app creates a Shopify automatic shipping discount; qualifying carts get free or reduced shipping with no action. |
| Code | The app creates a Shopify shipping code discount; the shopper must enter the code to get the free or discounted shipping. |
With the Code type the app creates the shipping code in Shopify for you. The shopper enters it to unlock the shipping benefit (free shipping, a fixed amount off, or a percentage off the shipping cost — see /docs/guides/discounts/shipping-discounts for the value options). Use the Code type when free shipping should be a reward you distribute, rather than something every cart receives.
Which funnels support promo-code triggers
Promo-code triggers (the Applied discount codes condition) are only available on three campaign types:
- Gift with purchase
- Auto-add
- Checkout upsell
No other funnel supports the promo-code trigger. If you are building a pre-purchase, post-purchase, or product-page recommendation campaign, the "Applied discount codes" condition will not be available — and a code applied by the shopper will not gate those offers. Move the logic into a gift-with-purchase, auto-add, or checkout campaign instead.
This restriction applies only to the trigger. Code-based tier and shipping discounts are configured on the discount itself, not on a campaign funnel, so they are not limited to these three types.
Matchers: Equals vs Starts with
A promo-code trigger can match the applied code two ways:
| Matcher | Behavior | Use it for |
|---|---|---|
| Equals | Exact match — the applied code must equal the code you entered, character for character. This is the default. | A single, specific code like INFLUENCER20 |
| Starts with | Prefix match — any applied code that begins with your text matches. | A whole family of generated codes, like SUMMER* |
Starts with is what lets one rule cover many codes. If you generate hundreds of unique codes that all share a prefix (for example SUMMER-A1, SUMMER-B2, …), a single Starts with SUMMER rule matches all of them — you do not have to list each code. With Equals, you would need one rule per code.
How an applied code is resolved at runtime
When a shopper applies a code at the cart, the app does a little work behind the scenes before a triggered offer can appear:
- The applied code is uppercased, so matching is case-insensitive (
summer20andSUMMER20resolve the same way). - The code is resolved through the storefront proxy, and the lookup result is cached for about one hour.
A short delay after a shopper applies a code — before the triggered offer shows up — is normal. The storefront has to resolve the code and your campaign conditions before the offer can render. This is expected behavior, not a bug.
Validation outcomes and errors
When the storefront validates a discount code, it checks the code against Shopify and can surface one of the following outcomes. Use this table to diagnose what a shopper is seeing.
| Error | Plain-English meaning | What to check |
|---|---|---|
| Invalid | The discount code does not exist. | Confirm the code text is spelled correctly and the discount exists in Shopify. |
| Already applied | The code is already applied to this order. | Nothing to fix — the code is already in effect on the cart. |
| Removable at checkout | The code can only be removed at checkout. | Inform the shopper they can remove it on the checkout page if needed. |
| Limit reached | The code has exceeded its usage limit. | Raise or remove the usage limit on the discount in Shopify, or issue a new code. |
| Inactive | The discount is no longer active. | Check the discount's status and active date range in Shopify; reactivate or extend it. |
| Not found | The code was not found in the system. | Verify the code exists and is published; re-create it if it was deleted. |
| Rate limit exceeded | Too many validation requests in a short window. | Have the shopper wait a moment and retry; this clears on its own. |
| Missing code | No code was provided. | The shopper submitted an empty field — prompt them to enter a code. |
| Validation error | An internal error occurred during validation. | Retry; if it persists, this is a system-side issue rather than a configuration problem. |
Discount-code validation results are cached for about three minutes and the validation endpoint is rate-limited. If you change a discount in Shopify, allow a few minutes before the storefront reflects it. A burst of rapid validation attempts can briefly produce Rate limit exceeded.
Keeping your codes healthy
A promo-code trigger only stores a reference to a code. If the underlying Shopify discount is later disabled or deleted, the trigger still points at a code that no longer works.
When a campaign's trigger references a disabled or deleted discount code, the app shows a warning icon on the campaign. The campaign's offer can no longer fire from that code, because the code the shopper applies will never validate. Re-create or re-enable the code in Shopify (keeping the exact same code text), or update the campaign's condition to point at a code that is still active.
Make a habit of checking for the warning icon after you clean up discounts in Shopify Admin — disabling a coupon there has a silent knock-on effect on any campaign that triggers off it.
Recipes
Troubleshooting
Combining app discounts with Shopify discounts
How to configure Llama Upsells discounts so they coexist with Shopify coupon codes and other apps' automatic discounts.
Cart restrictions
Block or warn shoppers at the cart and checkout based on cart conditions, with custom error messages and flexible rules.