Kitvel Promotions — User Manual

Five automatic promotions in one app. No discount codes. Free during launch.

Kitvel Promotions runs five promotion types — tiered spend discounts, quantity discounts, Buy X Get Y (BOGO), free shipping thresholds, and free gifts — as fully automatic Shopify discounts. Shoppers never type a code; the right discount applies itself in the cart and at checkout. Discounts are calculated by Shopify Functions, so the cart and checkout always agree.

This manual covers the current version of the app: the step-by-step promotion editor, drafts, storefront widgets, analytics, Shopify Sidekick, and settings.

Quick Start

1. Install the app from the Shopify App Store. Kitvel Promotions is completely free during launch — no trial period, no order caps, no feature locks, and no card required.
2. Create a promotion. From the promotions list, click Create promotion. Pick a ready-made template or start from scratch (see Templates).
3. Walk through the editor. The left sidebar shows four steps: Promotion type, Promotion settings, Storefront, and Review & save. Set your rules, choose where the promotion shows on your storefront, then publish.
4. Test in your storefront. Add the qualifying items to your own cart and confirm the discount appears with the right amount.
5. Watch the results. Open Analytics in the app to see which orders each promotion discounted (new orders appear within about 30 minutes).

Tip: Start with one promotion, test it, then add the next. A promotion is only live after you publish it in the final step — see Draft or published?

Creating a Promotion

The editor

Every promotion is created and edited in the same four-step editor:

Your promotion's name matters beyond the app: when a promotion is published, Kitvel creates one automatic discount in your Shopify admin with exactly that name (Shopify admin → Discounts). Renaming a promotion renames its discount.

Templates

The Promotion type step offers one-click templates — preconfigured promotions you can publish as-is or adjust first:

Draft or published?

Moving on from Promotion settings saves your work as a Draft. A Draft is not live:

• No discount is created in Shopify for a Draft.
• Nothing shows on your storefront for a Draft.
• The promotions list marks it with a Draft badge.

To go live, finish the Storefront step (at least one placement must be switched on) and click Save & publish on Review & save. Publishing creates the promotion's automatic discount in Shopify.

Scheduling

In Promotion settings, each promotion either runs continuously (active until you pause it) or runs on a schedule with a start and end date/time. Scheduling uses Shopify's native discount scheduling: a scheduled promotion appears in Shopify with its start/end dates, shows as Scheduled in the app before it starts, and as Ended after it finishes. Times follow your store's timezone.

Checkout messages

Each promotion has a Checkout message (shown to buyers) — the text shoppers see next to the discount in the cart and at checkout. Leave it blank to use the default for that type, or write your own with these variables:

For a Buy X Get Y promotion with a reward discount below 100%, the default message is Buy {buyQty}, get {rewardQty} {percent}% off.

The Five Promotion Types

1. Tiered Discount (spend-based)

What it is. An order-level percentage discount that grows with the cart subtotal. The more a shopper spends, the bigger the percentage off the entire order.

When to use it. Raising average order value — "10% off $100+, 15% off $200+, 20% off $300+" nudges shoppers over the next threshold.

How to set it up.

1. Create a Tiered discount promotion (or pick a Spend Tiers template).
2. Add tiers: each tier has a Spend minimum and an Off (%) percentage. Only the highest qualifying tier applies — tiers never stack on each other.
3. Set the schedule and checkout message, complete the Storefront step, and publish.

What shoppers see. A single order-level discount in the cart and at checkout, e.g. "25% off orders over $400 −$150.00".

Configuration example.

A $600 cart hits the top tier: 25% off = −$150.00, subtotal $450.00.

2. Quantity Discount

What it is. A product-level percentage discount triggered by buying enough units of an eligible product. Each cart line is evaluated on its own quantity: when the quantity of an eligible product line reaches a tier, that line gets the discount.

When to use it. Bulk incentives and multi-packs — "buy 3, save 5%". Works well for consumables, apparel, or any product where stocking up makes sense.

How to set it up.

1. Create a Quantity discount promotion.
2. Choose All products or Specific products (then pick products with Shopify's native picker).
3. Add tiers: each tier has a Quantity minimum and an Off (%) percentage. The highest qualifying tier applies to that line.
4. Set the schedule and checkout message, complete the Storefront step, and publish.

What shoppers see. The discounted price on the product line, with a discount message such as "5% off when you buy 3+".

Configuration example.

Three $600 snowboards in one line: 5% off = −$90.00, line total $1,710.00.

Note: the discount is evaluated per product line. Three units of Product A and three units of Product B each earn their own tier — quantities are not pooled across different products.

3. Buy X Get Y

What it is. The classic BOGO: buy a number of items, get reward items free or at a discount. Trigger products (what the shopper must buy) and reward products (what gets discounted) are always configured separately — only reward products receive the discount.

The two modes. In Promotion settings, the mode switch decides how the buy quantity is counted:

• Specific products — each selected trigger product must reach the buy quantity on its own. Quantities are never combined across different trigger products. Buy 2 with a cart of 1 snowboard + 1 pair of boots earns nothing; 2 snowboards earns.
• Mix & match — quantities combine across all selected trigger products. 1 snowboard + 1 pair of boots satisfies "buy 2".

Storewide BOGO is simply a promotion with both trigger and reward products set to All products.

Two built-in behaviors apply in both modes:

• Free reward applies to: Cheapest / Most expensive. When several items could be the discounted reward, the cheapest is discounted by default. Switch to Most expensive only if you genuinely want to give away the priciest item.
• Price cap (always on, not configurable). A reward item can never go free if it costs more than the most expensive trigger item in the cart. This prevents abuse such as buying two $25 items and getting a $600 item free.

A single unit can never count as both trigger and reward, so when trigger and reward products overlap, each set needs buy + reward items in the cart (buy 2 get 1 needs 3 units).

How to set it up.

1. Create a Buy X get Y promotion.
2. Choose the mode: Specific products or Mix & match.
3. Choose All products or Specific products separately for trigger products and reward products. For rewards, the picker lets you select specific variants — only the variants you check receive the discount.
4. Set Buy quantity, Get reward quantity, and Reward discount (%) (100% = free; set lower for a discounted reward, e.g. 50% = half price).
5. Pick the free-reward order (Cheapest / Most expensive).
6. Set the schedule and checkout message, complete the Storefront step, and publish.

What shoppers see. The reward item's line drops to $0.00 (or the discounted price) with a message such as "Buy 2, get 1 free".

Important: shoppers must add the reward item to their cart themselves — Shopify cannot auto-add products to a cart. Announce the deal where shoppers will see it (the product page offer box and announcement bar placements work well).

Example (Specific products): Buy 2 snowboards (triggers), get 1 wax kit free (reward). A cart with 2 snowboards + 1 wax kit makes the wax kit $0.00. A cart with only 2 snowboards gets nothing — the reward must be in the cart.

Example (Mix & match): Buy 2, get 1 free; triggers and rewards are both all products. A cart with a $785.95 board, a $600.00 board, and a $24.95 wax kit: the two boards are paid for, the wax kit goes free, subtotal $1,385.95.

4. Free Shipping

What it is. A shipping-level discount: when the order subtotal reaches your threshold, shoppers get free shipping at checkout.

When to use it. Reducing cart abandonment — a visible "Free shipping over $75" gives shoppers a clear goal to reach.

How to set it up.

1. Create a Free shipping promotion.
2. Set Free shipping on orders over ($).
3. Set the schedule and checkout message, complete the Storefront step, and publish.

What shoppers see. Nothing changes in the cart itself — shipping discounts appear at checkout. After entering a shipping address, the shopper sees a free ($0.00) shipping option alongside the regular rates.

Configuration example.

A $90 cart qualifies; a $60 cart does not.

Note: because this is a delivery discount, you can only verify it by going through checkout to the shipping step — it never appears on the cart page. The cart and side-cart progress bars (see Storefront Widgets) can still show shoppers their progress toward the threshold.

5. Free Gift

What it is. A product-level 100%-off discount: when the order reaches your threshold and the gift product is in the cart, the gift becomes free (up to your max-gifts-per-order limit).

When to use it. Threshold gifts — "free wax kit on orders over $100". Handy for moving slow inventory or sweetening high-value orders.

How to set it up.

1. Create a Free gift promotion.
2. Choose All products or Specific products for the gift selection. With Specific products, the picker lets you select specific variants. You can offer several gifts and let the customer choose with the gift picker widget.
3. Set Free gift on orders over ($) and Max gifts per order (1–10).
4. Choose which item becomes free when several could qualify — Cheapest (default) or Most expensive.
5. Set the schedule and checkout message, complete the Storefront step, and publish.

How the threshold is counted. For specific gift products, the gift's own value doesn't count toward the threshold — a shopper can't reach the threshold by adding the gift itself. The rest of the cart must reach the threshold on its own.

What shoppers see. The gift line drops to $0.00 with a message such as "Free gift on orders over $100".

Important: like Buy X Get Y, the gift must be in the cart — Shopify cannot auto-add it. The gift picker widget (below) solves this: it shows eligible gifts on the product page and lets the shopper add one in a click.

Configuration example.

A $600 snowboard + wax kit in the cart: wax kit $0.00, subtotal $600.00.

Managing Promotions

The promotions list is your home base. Each row shows the promotion's name, type, status, priority number, and placement dots (H = Home, P = Product, C = Collection, T = Cart, D = Drawer) showing where its widget appears.

Statuses

Pause, resume, delete

• Pause a promotion to stop it without losing its setup — for example during a sitewide sale. Resume it any time to go live again.
• Delete removes the promotion and its Shopify discount permanently.
• Edit reopens the four-step editor. Changes go live when you save and publish again.

The 25-discount limit

Shopify allows a maximum of 25 active automatic discounts per store, across all apps combined — not 25 per app. If your store already has many automatic discounts (from Kitvel or other apps), Shopify will refuse to create another one and the promotion cannot go live until you free up a slot. Pause or delete discounts you no longer need if you hit this limit.

Storefront Widgets

Publishing a promotion creates the discount. Widgets are how shoppers learn about it before checkout. In the editor's Storefront step you choose placements for that promotion, tune its colors and messages, and preview the result:

Each placement can be switched on or off per promotion. The preview panel shows a desktop and mobile mockup, and the Appearance card lets you set the bar color, text color, and background, plus a custom message per placement (leave blank for the default).

Adding the theme blocks

Placements are rendered by Kitvel's theme blocks. Open Settings → Storefront → Theme integration to check the app embed status and jump into the theme editor, where you can add the blocks:

• Kitvel Announcement Bar — home page
• Kitvel Product Offer — product pages
• Kitvel Collection Banner — collection pages
• Kitvel Progress Bar — cart page
• Kitvel Side Cart Progress — cart drawer
• Kitvel Gift Picker — product pages (lets shoppers choose and add a free gift)

Widgets read their display settings from your shop's stored configuration — there is no theme code to edit, and the blocks update when you change settings in the app.

Progress bar and gift picker placement

Two widgets have extra placement options, under Settings → Storefront → Widget placement:

• Progress bar (cart page) and Gift picker (product page) each have a placement method: Recommended (Hybrid) — use the theme block if available, otherwise insert automatically with JavaScript; Theme editor (App block); or Automatic injection (JS).
• Positions: the progress bar can sit above the cart items, above the subtotal, or above the checkout button; the side-cart progress bar can sit at the top of the drawer or above/below the checkout button; the gift picker can sit above the Add to cart button, below it, or below the product form.

Global widget settings

Under Settings → Storefront you can also:

• Turn all storefront widgets off (Theme integration tab) without affecting discounts — promotions keep applying at checkout; only the on-page widgets hide.
• Set default widget colors for new promotions (Appearance tab).
• Add Custom CSS & JS applied to all Kitvel widgets (Custom CSS & JS tab).

How Promotions Combine

You can run all five promotion types at once. Promotions apply at three levels, and different levels combine:

One product-level discount per item. When two product-level promotions could discount the same item, only one applies to that item: the one with the higher priority. Priority is the promotion's position in your list — the higher a promotion sits, the higher its priority. The losing promotion still works normally on items it doesn't contest.

One order-level discount. Within a tiered promotion, only the highest qualifying tier applies. Different levels still stack: a shopper can get a product-level discount on an item, a tiered discount on the order, and free shipping — all in the same order.

Worked example. Promotions (in list order): 1) Buy X Get Y — buy 2, get 1 free; 2) Quantity discount — 3+ units, 5% off; 3) Tiered discount — 25% off orders over $400. Cart: 3 × $600 snowboard = $1,800.

• Product level: Buy X Get Y and the quantity discount both qualify, but Buy X Get Y has higher priority, so it wins: 1 snowboard free (−$600.00).
• Order level: the tiered discount stacks on top: 25% off the remaining $1,200 = −$300.00.
• Final subtotal: $900.00, with two discount lines shown.

Practical advice: put your most generous product-level offer highest in the list. Under Settings → Advanced → Promotion conflict handling you can review how conflicts between promotions are resolved.

Analytics

Analytics (in the app's main navigation) shows what your promotions actually did:

• Discount orders — orders where at least one Kitvel promotion applied.
• Revenue from promo orders — total revenue from those orders.
• Total discounts given — the total discount amount Kitvel promotions gave.
• Avg order value — average value of promotion orders.

Below the cards, By promotion breaks orders and discounts down per promotion, and Promotion orders lists one row per order × promotion, so an order that used two promotions appears once for each. Use the From / To date range and the Promotion filter to narrow the view, and Export CSV to download the detail rows for your own analysis (for example, joining them with ad spend).

How it works. The app checks your store's new orders in the background and records the ones where a Kitvel discount applied — the order number, date, amounts, items, which promotion applied, and the discount amount. New orders usually appear within about 30 minutes; they are not instant. Attribution is by promotion, so you can see exactly which promotion produced each discount.

Privacy note. Analytics works with order-level data only. The app does not request or store your customers' names, email addresses, phone numbers, or postal addresses. See the privacy policy for details.

Shopify Sidekick

Kitvel Promotions works with Shopify Sidekick, the AI assistant built into your Shopify admin. There is no setup and no API keys: ask Sidekick to create or edit a promotion, and it opens Kitvel Promotions with the right page ready. Sidekick asks for your approval on an approval card before anything happens, and you always review and confirm in the app before a promotion is saved.

Try asking Sidekick:

• "Create a buy 2 get 1 free promotion"
• "Create a free shipping promotion for orders over $75"
• "Set up a spend more, save more promotion"

The same examples are listed under Settings → AI & Integrations. Specific English phrasing works best — name the promotion type and the key numbers (quantities, threshold) in your request.

Settings

Settings is organized into seven sections:

Testing Checklist

Before announcing a promotion to customers, walk through this checklist in your own storefront:

1. Published, not Draft. In the promotions list, confirm the promotion shows Active (not Draft), and check Shopify admin → Discounts for an automatic discount with the promotion's name.
2. Single promotion, happy path. Add exactly the qualifying items. Confirm the discount appears with the right message and amount, and the subtotal math is correct.
3. Below the threshold. Remove one item so the cart no longer qualifies. Confirm the discount disappears entirely — no partial or stuck discounts.
4. Boundary quantities. For quantity and BOGO tiers, test one unit below, exactly at, and one unit above each threshold.
5. Widgets. Visit each placement you enabled (home, product, collection, cart, side cart) and confirm the widget renders. If a placement is missing, check that the matching Kitvel block is added in the theme editor and that widgets are enabled under Settings → Storefront.
6. Overlapping promotions. Enable everything you plan to run together and build a cart that qualifies for several at once. Confirm one product-level discount per item and that order/shipping discounts combine as expected.
7. Free shipping. Go all the way to checkout's shipping step with an address entered. Confirm the free shipping option appears — and that a below-threshold cart does not show it.
8. Free gift / BOGO without the reward in cart. Confirm nothing happens (no error, no discount) when the threshold is met but the gift or reward product isn't in the cart — then add it and confirm the discount applies.
9. Mobile. Repeat the happy path on a phone.
10. Analytics. After a test order, check Analytics later (orders appear within about 30 minutes) and confirm the order is attributed to the right promotion with the right discount amount.

If anything looks wrong, double-check the promotion's product selection, thresholds, schedule, and status, save and publish again, and retest.

Frequently Asked Questions

Do shoppers need a discount code?

No. Every promotion in Kitvel Promotions is fully automatic. Eligible carts are discounted with no code, no link, and no extra click.

Is the app really free?

Yes — during launch, Kitvel Promotions is completely free: all five promotion types, widgets, and analytics included, with no trial period, no order caps, and no feature locks. Your current plan is shown under Settings → Usage & billing.

Can I run more than one promotion at a time?

Yes. Create as many promotions as you need and run them together — see How Promotions Combine. Keep Shopify's limit in mind: at most 25 active automatic discounts per store across all apps.

What's the difference between "All products" and "Specific products"?

All products covers your entire catalog, including products you publish in the future. Specific products opens Shopify's native picker so you can hand-pick exactly which products qualify. For BOGO rewards and gifts, you can also pick specific variants.

What's the difference between "Specific products" mode and "Mix & match" mode in Buy X Get Y?

They answer different questions. The picker choice decides which products are triggers/rewards. The mode decides how the buy quantity is counted: in Specific products mode, one trigger product must reach the buy quantity on its own; in Mix & match mode, trigger products combine toward it.

Why do draft or archived products show a warning in my selection?

Customers can't buy draft or archived products, so they can never trigger a promotion. If a product you selected is later archived, it stays in your list with a status badge as a reminder to remove it.

The Buy X Get Y reward isn't going free. Why?

Three common causes: (1) the reward item isn't in the cart — shoppers must add it themselves; (2) the buy condition isn't met — in Specific products mode, no single trigger product reaches the buy quantity on its own; (3) the built-in price cap blocks it — the reward costs more than the most expensive trigger item in the cart.

Why didn't the free gift apply?

The gift product must be in the cart, and the rest of the cart must reach your threshold (the gift's own value doesn't count toward it). Check both — or add the gift picker widget so shoppers can add the gift in one click.

Why is there no free-shipping line in the cart?

Free shipping is a delivery discount — it only appears at checkout, on the shipping step after the shopper enters an address. It never shows on the cart page. This is a Shopify platform behavior, not an app limitation.

My promotion is saved but nothing happens in my store.

Most likely it's still a Draft: a promotion goes live only after you complete the Storefront step (at least one placement on) and click Save & publish. Also check that the promotion isn't paused, that its schedule covers today, and that Settings → General has the app enabled.

My widget isn't showing.

Check, in order: the promotion is published with that placement switched on; the matching Kitvel block is added in the theme editor (Settings → Storefront → Theme integration shows the embed status); and storefront widgets are enabled globally under Settings → Storefront.

Why don't I see my order in Analytics yet?

Orders are collected in the background and usually appear within about 30 minutes. Only orders where a Kitvel discount applied are recorded.

Can I exclude sale items or specific collections?

Product eligibility is controlled per promotion via the All products / Specific products choice. There is no collection picker or sale-price exclusion in the current version — use Specific products and pick exactly what qualifies.

Does the app work with Shopify Markets / multi-currency?

Discounts are calculated by Shopify in the cart's currency. Spend thresholds you enter are compared against the cart subtotal as entered — for single-currency stores this is exact. If you sell in multiple currencies via Shopify Markets, thresholds are not auto-converted; set them with your primary market in mind and test in each market.

Will promotions apply to draft orders created in admin?

Automatic discounts apply to the online store cart and checkout. Draft orders created manually in the Shopify admin do not run Shopify Functions, so app discounts won't apply there.

Pricing

Kitvel Promotions is free during launch. All features are included — the five promotion types, the template library, storefront widgets, analytics, and Sidekick support — with no trial period, no discounted-order caps, and no feature locks. During launch, no billing approval is requested and no payment method is required. Your plan ("Founding Member — Free") and this month's discounted-order count are shown under Settings → Usage & billing.

Support

Questions or feedback? Email support@kitvel.com. See also the FAQ page.

Last updated: October 24, 2026.