> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shoppex.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Run a Black Friday sale with coupons and email

> Coupons, scheduled email blasts, segments, and tracking — from prep to post-mortem.

A two-week walkthrough for running a major sale on Shoppex. Built around Black Friday but
the same playbook works for any limited-time promotion — Cyber Monday, end-of-quarter,
launch sales.

## What you'll do

* Prep your catalog (which products are on sale, by how much).
* Create coupon codes, with limits and product-targeting.
* Build the buyer list to email and Telegram-blast.
* Schedule the email campaign for the moment the sale opens.
* Track conversions live and react if something underperforms.
* Run the post-mortem.

## Two weeks before — prep

### Pick the discount strategy

Coupon types Shoppex supports:

* **`PERCENTAGE`** — N% off the order.
* **`FIXED`** — fixed-amount discount.

(There's no built-in BOGO — for buy-one-get-one, use bundle products instead.)

For each coupon, configurable limits:

* `maxUses` — total redemptions across all buyers (cap the exposure).
* `minOrderAmount` — minimum order subtotal to be eligible.
* `maxDiscount` — cap the absolute discount (useful for percent codes on big orders).
* `validFrom` / `validUntil` — time window. Coupon code returns invalid outside these times.
* Product / variant binding — restrict to specific products. Without bindings, coupon
  applies to anything.

Decide your codes:

* A general code (`BF25` for 25% off everything, capped at \$X).
* Product-line specific codes (`PRO-BF` for the Pro tier only).
* VIP code with bigger discount, low max-uses, shared only with your top customers.

Create them at **Discounts** (`/coupons`).

### Build your email lists and segments

In **Marketing → Email** (`/marketing/email`), your list of buyers is automatically
maintained. Build segments based on what you want to target:

* All past buyers.
* Buyers in the last 90 days (recent + warm).
* High-value buyers (LTV > \$X).
* Trial-only buyers (never converted to paid).

Segments are saved filters — once built they stay current as new customers come in.

### Draft the email

Email Marketing's template system is **MJML-based**. You can either:

* Use the **builder** to drag-and-drop the email.
* Write MJML directly if you want pixel-precise control.

Personalize with variables — first name, the buyer's most-bought category, the discount code
itself. Variables come from the campaign-recipient context.

Test sends to yourself before scheduling — broken templates render different per mail
client.

### Build a parallel Telegram blast (if you use Telegram)

Same idea on Telegram side. **Store → Telegram → Broadcasts → New broadcast.**

* Pick the target segment.
* Compose the message (include the coupon code or a deeplink).
* Schedule for the same moment as the email.

## Sale day — go live

### Schedule everything in advance

Don't manually hit "Send" at 9am — set the schedule the night before. Both campaigns
(`emailMarketingCampaigns.scheduleAt`) and Telegram broadcasts support scheduled send. You
wake up to the campaigns already going out.

Make sure your coupons' `validFrom` matches the announcement time. If you email at 9am with
a code that says "valid from 10am", buyers will hit "invalid code" at the first 100 attempts
and you've lost them.

### Watch the dashboard

During the sale, your live indicators:

* **Analytics → Revenue** (`/analytics`) — running revenue total.
* **Orders** page — orders coming in, filterable.
* **Email campaign status** — sent / delivered / opened / clicked counts, available per
  campaign.
* **Telegram broadcasts** — same kind of stats, per broadcast.

Shoppex doesn't have a built-in "coupon analytics dashboard" — to see how many sales each
code drove, filter Orders by coupon code (every order with a redeemed coupon has it
attached) and read the count + revenue from there.

### React if something underperforms

If the email got delivered but conversions are flat, consider:

* A follow-up email 12-24 hours later with a different angle (urgency, social proof).
* Lower the coupon's `minOrderAmount` if you're getting "cart abandoned because code didn't
  apply" complaints.
* Spawn a deeper discount code for an off-hours segment.

If conversions are *too* strong on a wholesale-margin product, you can mark the coupon
inactive mid-sale — buyers who already redeemed are unaffected, but new attempts fail.

## After the sale — post-mortem

Within a few days of close:

1. Filter Orders by each coupon code. Count: total redemptions, average order value, total
   revenue.
2. Compare against the same week last month (or last year if you have one) to see net lift
   vs. just-discount-already-existing-buyers.
3. Check Email Marketing stats: open rate, click rate, conversion rate per campaign.
4. Note the segment that converted best — that's where you push for the next campaign.

Save the coupons but mark them inactive — keeping the codes intact preserves your
historical record (orders that redeemed them stay linked).

## Common pitfalls

* **Forgetting `maxUses`** on a percent code shared publicly. Someone leaks it; you're
  refunding a thousand orders. Always cap.
* **Email templates that break on iOS Mail.** Test before scheduling. MJML compiles to
  cross-client HTML but you still want to eyeball it.
* **Coupon stacking.** Shoppex applies one coupon per cart. If buyers complain "I can't use
  both codes," that's expected — pick which one wins (usually the bigger).
* **Shipping a sale on a day where one gateway is down.** Test Stripe, PayPal, crypto
  *before* the announcement goes out.