Promotions

Plans: Pro · Agency

Experimental

The Promotions feature is in active development. CRUD works, intent detection works, analytics are incomplete. Treat this as a preview, not a production tool yet.

Promotions are AI-issued coupons that the LLM can recommend to shoppers asking conversational questions like "is there a discount on this?" or "do you have any current offers?". The coupon code, the rules, and the targeting all live in Clione — your storefront platform sees only the redeemed coupon at checkout, the same as any other promo code.

---

Where it lives

Per store: Store → Promotions. Plan-gated (coupon_basic feature).

The page shows:

• The list of promotions for this store.
• + New promotion button.
• Per-row: name, status (active / paused / scheduled / ended), redemptions count.

---

Creating a promotion

1. Click + New promotion.
2. Fill the form:
   • Name — internal label.
   • Coupon code — what the shopper enters at checkout (or what the LLM suggests).
   • Discount type + amount — percentage off, fixed amount, free shipping.
   • Eligibility — all products, or filter by category / tags / SKUs.
   • Validity — start date, end date, max redemptions.
   • Intent triggers — keywords or intent classes the LLM watches for (e.g. "abandoned cart", "first-time buyer", "price-sensitive").
3. Save as Draft or Active.

Once active, the coupon is included in the agent context Clione provides to ChatGPT, Perplexity, etc. via the MCP server and the agent-discovery endpoint. When a shopper's question matches the intent triggers, the LLM may surface the coupon.

---

Pausing / activating / deleting

Row menu:

• Pause — coupon stays in DB but is excluded from agent context. Redemptions still count toward the max.
• Activate — re-includes in agent context.
• Delete — permanent. Past redemptions are kept in analytics.

---

Per-platform notes

Promotions are platform-agnostic on the Clione side, but the coupon code itself must exist in your storefront platform's promotion system for the redemption to actually apply at checkout.

BigCommerce

Manual mirror in BC:

1. Open BigCommerce admin → Marketing → Promotions.
2. Click Add.
3. Configure the promotion to match what you set in Clione:
   • Apply to → match the eligibility filter (category, brand, or SKU list).
   • Coupon code → must be exactly the same string as the Clione coupon code (case-sensitive).
   • Discount → match percentage/fixed/free-shipping and amount.
   • Validity dates → match.
   • Usage limit → match the Clione max-redemptions.
4. Save and Activate.

Why the manual mirror is required: Clione doesn't currently push to BC's /v3/marketing/promotions (on the roadmap). Without the BC-side coupon, the shopper sees the LLM's discount suggestion but BC checkout rejects the code.

Redemption webhook: BC's store/cart/converted webhook is wired in Clione. When a cart that used a Clione-managed coupon converts, the redemption count in the Clione dashboard ticks up within ~30 seconds.

Shopify

Manual mirror in Shopify:

1. Open Shopify admin → Discounts.
2. Click Create discount → pick the discount type (Amount off products, Amount off order, Free shipping, Buy X get Y).
3. Configure to match what you set in Clione:
   • Discount code → exactly the same string as the Clione coupon code (case-sensitive).
   • Applies to → match the Clione eligibility filter.
   • Customer eligibility → All customers, or restrict to a customer segment if you set the same in Clione.
   • Maximum discount uses → match the Clione max-redemptions.
   • Active dates → match.
4. Save.

Why the manual mirror is required: Same as BC — Clione doesn't yet create Shopify discounts via the Admin API. The Shopify GraphQL discountCodeBasicCreate mutation is on the roadmap.

Redemption webhook: Shopify webhook handling is partial — the orders/create webhook fires reliably, but the discount_code attribution can be inconsistent if the discount was applied via the Shopify Function. Treat the analytics counts as approximate until this is firmed up.

Programmatic creation roadmap

Both platforms expose APIs to create coupons. The reason they're not auto-created today is a deliberate safety check during the experimental period — we don't want to push promotions to your live storefront that you can't audit. Once analytics + audit logs are in place, auto-push will be opt-in per store.

---

Analytics

The analytics view shows:

• Redemption count over time.
• Top intent triggers that surfaced the coupon.
• LLM provider attribution (ChatGPT vs Perplexity vs others).

Note: analytics depends on the storefront passing the redeemed code back via webhook. This is wired for BigCommerce; Shopify webhook handling is partial.

---

Troubleshooting

Coupon never surfaces in ChatGPT — Common causes:

1. The intent triggers don't match what users are actually asking. Broaden them.
2. The coupon's eligibility filter is too narrow.
3. Your tenant's MCP / agent-discovery endpoint isn't reachable from the LLM's network. Check Org → MCP for status.

Coupon surfaces but discount doesn't apply at checkout — The code exists in Clione but not in the storefront platform. Create the matching coupon in BC / Shopify with the same code, value, and rules. Case sensitivity matters on both platforms — SAVE10 and save10 are different codes.

Promotions tab is locked — Your plan doesn't include coupon_basic. Upgrade to Pro or Agency.

BigCommerce redemption count never updates — Verify the store/cart/converted webhook is registered. In BC admin → Settings → API → Webhooks. If the webhook is missing, disconnect and reconnect the store from the Clione Store → Settings screen; the reconnection registers webhooks.

Shopify redemption count is off by several — Known limitation: when a discount is applied via a Shopify Function (e.g. a buy-X-get-Y rule), the discount_code attribution on the orders/create webhook can be empty. The order still completes; only the analytics tally is missed. This is on the fix list.

Intent triggers fire on the wrong question — Triggers are matched semantically, not by exact string. If "abandoned cart" is triggering on "is this in stock?", the LLM is over-generalising. Tighten the trigger by adding negative keywords (e.g. abandoned cart but not stock) in the trigger field.

Intent trigger catalogue

The intent classes the LLM is trained to detect:

Intent	Typical question pattern	Best fit
discount_request	"do you have a discount?"	Generic promos
abandoned_cart	LLM detects shopper has been comparing for a while	Cart-recovery promos
first_time_buyer	"first time buying" / no prior reference to the brand	Welcome promos
price_sensitive	"what's the cheapest option" / "budget version"	Entry-tier promos
bundle_intent	"do you have a set/kit?"	Bundle promos
gift_intent	"as a gift for X"	Gift promos
subscription_intent	"I need this regularly"	Subscription promos
seasonal	references holiday / season	Seasonal promos
loyalty	references previous purchase or membership	Loyalty promos

You can stack multiple intents on a single promotion — the LLM surfaces it if any of them match.

Best practices

• Always create the matching platform-side coupon first. A surfaced code that doesn't apply at checkout breaks shopper trust more than not surfacing a code at all.
• Set realistic max-redemption caps. Without a cap, a viral mention in a popular LLM thread can drain promo budget overnight.
• Use unique codes per channel. If you also use the same codes for email marketing, attribution gets murky.
• Review the analytics weekly. The Promotions analytics view shows which intents are surfacing your coupons — if "discount_request" never fires but "bundle_intent" does, retire the discount and lean into bundles.

Data attribution

When a redemption is attributed to a Clione-surfaced coupon, the analytics row tags it with:

• Originating intent class.
• LLM provider (when detectable from the referer chain).
• First-touch timestamp (when the LLM first surfaced the code).
• Time-to-conversion (in hours/days).

Attribution is best-effort — LLM providers don't always pass a referer or a click ID. The aggregate trend is what matters, not per-order precision.

Eligibility filter syntax

The eligibility filter accepts these forms:

• All products — empty filter; the coupon applies storewide.
• By category / collection — pick from a list. AND logic if multiple are picked.
• By tag — comma-separated. Matches any (OR).
• By SKU pattern — glob syntax, e.g. SKU-ABC-* matches all SKUs starting with SKU-ABC-.
• By price range — min/max in store currency.
• By vendor / brand — pick from list.

You can combine multiple filters; the LLM only surfaces the coupon when all filters match the product the shopper is discussing.

Geographic targeting

A coupon can be limited to specific countries. Pick from the country list under Advanced → Geographic targeting. The LLM uses the shopper's locale (when detectable from the LLM provider's session metadata) to gate the surfacing.

Note: many LLM providers don't expose location reliably. Geographic targeting is best-effort and should be backed by a platform-side geographic gate (BC: "Customer groups by location"; Shopify: Markets with discount rules).

Coupon code best practices

• Use unique codes — don't reuse the same code across channels (email, social, partners). Attribution becomes impossible.
• Avoid easily-guessable codes — SAVE10 is fine for limited-time promos but invites abuse for evergreen.
• Pick codes that read well in LLM output — short, memorable, all-caps. Codes with random characters look spammy.
• Mention the code prominently in the FAQ widget — if you have a FAQ "Do you have any discounts?", embed the promo code in the answer with a clear "expires X" note.

Limits today

• Max 50 active coupons per store.
• Max 5 intent triggers per coupon.
• Max 12 eligibility filters per coupon.
• Max 100 redemptions tracked per coupon per day (overflows are still allowed by the platform; only the analytics tally is capped).

Contact support if you hit these and need higher limits.

Where the coupon surfaces

When a Clione-managed coupon is active and its intent triggers match a shopper's question, the LLM may surface the code in:

• ChatGPT shopping flows — when the agent context exposes Clione's MCP.
• Perplexity product comparisons — same, via the agent-discovery endpoint.
• Other LLMs that consume MCP or the public JSON-LD — discoverable, but surfacing is at their discretion.

Surfacing is not guaranteed — each LLM provider has its own discretion about whether to mention coupons. The aggregate uplift over a 30-day window is the metric to watch, not per-conversation surfacing.