How coupons work

When someone wins, the plugin creates a real WooCommerce coupon with a unique code. The defaults for those coupons live on the Settings screen: the code prefix, how long they last, the usage limit, a minimum spend, whether they can be combined with other coupons, and whether the coupon is locked to the winner's email address. Because they are ordinary WooCommerce coupons, they work everywhere in your store and appear in your normal reports.

The Code prefix can hold the letters A to Z without accents, numbers, hyphens (-) and underscores (_), and is saved in capitals, the way the codes are written. A prefix you type with any other character, such as 20%OFF-, NOËL- or a space, is not saved: the prefix you had is kept, and the message after saving says why. When a settings file's prefix holds such a character, the rest of the file is imported, your own prefix is kept, and the message after importing says so.

Earlier versions saved a prefix with a % in it with characters missing, so 20%DESC- became 20SC-; if your prefix looks like that, type the one you want again, without the %. They also saved a prefix with an accent, a space or a symbol in it, such as NOËL-, while the codes left those characters out and began NOL-. Such a prefix stays as it is until you next save this screen; then it is saved the way your codes already begin, and the message after saving says so. Your codes begin exactly as they did before.

Expires after (days) counts on your store's clock, the one under Settings → General. A coupon won on 11 September with 7 days is valid until the end of 18 September, and that is the date the winner is told.

The result panel can show a button that applies the coupon to the winner's cart (Show a button to apply the coupon, under Settings → Messages). It works for a visitor with an empty cart too, and for a coupon locked to the winner's email it fills that address in as the cart's billing email, unless one has already been entered.

The winner's email is sent through WooCommerce, from the sender name and address set under WooCommerce → Settings → Emails, in the same template as your order emails.

Reminding winners of their code#

A winner often closes the popup and carries on shopping, and by the checkout the code is in their inbox. With Remind winners of their code on later pages switched on (under Settings → Messages), a small Your prize button stays on the shop's pages after a win. It sits in the launcher's corner, at the launcher's height. When the winner has no spins left, as with the default of one spin per email, the launcher steps aside while it shows. When Spins per email (under Settings → General) lets them spin again, the launcher stays for the next spin and the button sits just above it (just below it in a top corner). While both show, the range's other buttons in that corner, such as a table of contents, dark mode switch or cookie choices button, stand above the two of them. Once a spin in that browser, with the address the prize was won with, says no spins are left, the launcher steps aside. With the launcher switched off, or halfway up a side, it sits at the bottom left. On a phone it shows a gift mark alone.

Pressing it opens a small panel with the prize, the code, the date it is valid until, any conditions the prize carries, Copy code and Close for now. When Show a button to apply the coupon is on, the panel also has the result panel's apply button, with the same link and the same words. Close for now hides the button for the rest of the visit in that browser tab; a page opened in a new tab shows it again.

When Spins per email lets a shopper win more than once, a second win's code is kept beside the first rather than in its place. The button is then called Your prizes, and its panel lists every code kept, newest first, each with its own prize name, date, conditions, Copy code and apply button. The launcher stays while any of the emails those prizes were won with has a spin left. One browser keeps up to five codes: a sixth win lets the oldest go from the button, and that code still works from the winner's email.

A code leaves the button while it is in the cart, and the button goes when no code is left to show. The code counts as in the cart when the shopper opens the cart page with it applied, types it in on the cart page (the classic page or the Cart block), or, on a classic theme with a mini cart, when the mini cart is refreshed with it. If the cart is later found to hold another of the shopper's own codes instead, the first comes back to the button. That happens when the prize coupons have Cannot combine with other coupons switched on (the default) and the shopper applies a second code: WooCommerce takes the first one out. Otherwise, a code that has left the cart, taken out by the shopper or replaced by another of your coupons, is forgotten.

A code goes for good once it is in the cart at the checkout (the classic page or the Checkout block), once an order has used it, or once its coupon has expired. A coupon that never expires is remembered for 30 days. An order that failed to pay or was cancelled gives the code back, so it stays on the button. The button is not shown on the checkout or on the order received page.

It is on for a shop that installs the plugin now. A shop that already had the wheel keeps it off until someone switches it on, either under Settings → Messages or with Switch it on in the suggestion the Dashboard shows while the wheel is turned on. It works only while the wheel is turned on: turning the wheel off stops it too, and the codes still work from the winner's email.

Where the site runs WP Consent API (Cookie Consent by Traslatability hands its answers to it), the code is kept only for a shopper who has allowed preferences. A shopper who has not answered, or says no, still sees the code in the result panel and gets the email, but no button, and saying no later takes the button away.

What it does not do:

• The code is kept in the shopper's own browser, and is never sent anywhere. The site stores nothing new about the visitor. So the button appears in the browser the prize was won in, and not on the shopper's phone if they won on a computer. A shopper who clears their browser's data loses the button, not the coupon. Beside the code the browser keeps a short tag worked out from the email the prize was won with, not the email itself, so that a spin with another email does not change what the button does.
• If the code is used from another device, or put in the cart in a way other than those above (another plugin applying coupons, say), the button stays until the cart page is opened or the coupon's date passes.
• Turning the reminder or the wheel off hides the button but does not reach into shoppers' browsers: a code already kept there stays until they clear their browser's data. Nothing shows it.
• It does not follow the shopper to another site of a network: each site keeps its own.
• It does not open the wheel. A winner who may spin again does that with the launcher, which stays beside the button, or when the popup next opens on its own.
• It does not know about spins used on another device. If the winner's last spin is used there, the launcher stays in this browser until a spin here is refused for having no spins left.

A visitor who has not won anything downloads nothing for it: every page carries a small script, under 600 bytes once compressed, that looks for a prize in the browser, and the button's script and stylesheet are fetched only when there is one. The cart page and the checkout each carry a script of their own, under a kilobyte once compressed, that notes the codes in the cart. Pages stay the same for every visitor, so page caching works as before; only the cart page and the checkout, which WooCommerce keeps out of page caches, name what is in the cart.

Emailing winners before their code expires#

The Your prize button reaches the browser a prize was won in. A winner who read the win email on a phone and shops on a laptop hears nothing more, and the code can run out unused. With Remind winners before their code expires switched on (under Settings → Expiry Reminder), each winner gets one more email a few days before their code's last day.

• When. From 10:00 on your store's clock, Days before the last day before the code's last day (1 to 7, 2 by default). A code won on 1 October that lasts 7 days works until the end of 8 October, so with 2 days its reminder is due on 6 October at 10:00. The job is booked as the code is made, with WooCommerce's own scheduled actions, which run on WordPress's cron as WooCommerce's own jobs do: on a shop with little traffic and no server cron, it goes out with the first visit after that time.
• Which codes. Only codes that expire, and only when there is time for a reminder: a code must last longer than Days before the last day, because a reminder always falls on a later day than the win. A 1-day code with 2-day reminders gets none, and neither does a 2-day code with 2-day reminders, whose reminder would come on the day it was won, hours after the win email. When the codes from Coupon Defaults are too short, the screen says so under the settings. A prize with coupon rules and an expiry of its own counts its own days.
• Who. Where the form shows a consent tick box, only winners who ticked it. As the box is required to spin while it is shown, that is every winner who spun with it; a winner who played while the form showed no box gets the reminder, as they got the win email. It goes to the address the code is locked to, or, for a code that is not locked, to the address the winner entered.
• Once, and only while it is worth sending. When the moment comes, the plugin asks again: the switch is still on, the coupon is still published and not in the Bin, it has not been used in an order, it has not expired, and it has not been reminded before. A winner whose data was erased with Tools → Erase Personal Data gets nothing, as their address is no longer on the code, and neither does a winner you deleted on the Leads screen. A coupon deleted for good takes its reminder with it.
• When sending fails. If your site does not accept the email (a mail server that is down for a moment, say), it is tried once more an hour later. Refused again, it is not sent, and the job shows as failed, with the reason, under WooCommerce → Status → Scheduled Actions (hook trlw_expiry_email).
• Its own switch. It follows Remind winners before their code expires, not the wheel's own switch: a code already won keeps working with the wheel turned off, and so does its reminder.
• What it says. It has its own Subject, Heading and Body, in your site's language until you change them, and shares the win email's Footer line. It is written in your site's main language even when WooCommerce's scheduled actions happen to run from your own visit to wp-admin in another language. After your words it names the code's limits, such as a minimum spend, the products it is for or Not with other coupons, in a Conditions line. The placeholders are {customer_name}, {coupon_code}, {coupon_label}, {expiry_date} (the last day the code works), {apply_link} and {site_title}. {apply_link} is the link the result panel's apply button uses: it puts the code in the cart and, for a code locked to the winner's email, fills that address in as the cart's billing email. It is sent through WooCommerce, from your store's sender, in the same template as the win email.
• Trying it. Preview opens the email in a new tab, and Send me a test sends it to the email address on your WordPress profile. Both use a sample code and the wording as last saved, in your site's language, as a winner gets it. The sample's link goes to the cart without applying anything, and it has no Conditions line, since no coupon stands behind it.

Changing Days before the last day applies to codes won from then on: a reminder already booked keeps its day. Switching the reminder off stops every booked reminder from being sent while it is off, and switching it back on lets any whose day has not yet come go out as booked.

On the Dashboard, Expiry Reminders shows Reminders sent, and Used after a reminder: the codes used in a paid order placed after their reminder went. An order that is then cancelled, refunded in full or fails comes off it, as it comes off the Revenue card, and goes back on if it is paid again. From 20 reminders on, the second figure also shows its share of the reminders sent; under 20 it is a count alone, as a share of so few says little.

It is on for a shop that installs the plugin now. A shop that already had the wheel keeps it off until someone switches it on, under Settings or with Switch it on in the suggestion the Dashboard shows while the wheel is turned on. Either way it covers codes won from then on: nothing is booked for a code won before.

Each site of a network has its own switch, wording, reminders and counts.

Coupon rules for one prize#

Every coupon follows the defaults on the Settings screen unless its prize says otherwise. To give one prize limits of its own, such as a minimum spend, chosen products or categories, or a cap on how many items it applies to, make an ordinary coupon under Marketing → Coupons with those limits, then choose it in the prize's Coupon rules field on the Wheel screen. The field searches your own coupons by code, as you type it, so a code with a % in it, such as 30%BFRIDAY, is found too; the ones the wheel made for winners are never offered. A line under the prize says what the chosen coupon's limits are, for example Min spend £60.00 · Shoes only · Up to 1 item.

A second line appears when the chosen coupon is looser than the Coupon Defaults on the Settings screen, for example Unlike your coupon defaults: Can be combined with other coupons. A coupon made in WooCommerce can be used with other coupons unless you tick Individual use only on it, and the prize's codes follow the coupon you chose, so tick it there if that prize should not stack. The same line names a minimum spend, sale items or free shipping that the defaults have and the coupon does not.

When that prize is won, the winner's new code copies these from the coupon you chose, and nothing else: products, excluded products, categories, excluded categories, minimum spend, maximum spend, Individual use only, Exclude sale items, Limit usage to X items and Allow free shipping. Limit usage to X items is copied only onto a Percentage discount or Fixed product discount prize, the two types WooCommerce offers it for; a Fixed cart discount prize leaves it out, and its line under the prize does not name it. What stays as it was:

• The prize's own Type and Amount still set the discount.
• The code, the usage limits and the email lock come from the Settings screen, as for every other prize. The coupon you chose is never used up, and its own email list and usage count are never copied.
• Expires after (days) beside the field sets how long this prize's coupon lasts. Leave it at 0 to use the expiry on the Settings screen. The chosen coupon's own expiry date is not copied.

The coupon you choose stays a working coupon in its own right. If it exists only to hold rules, give it an amount of 0, so nobody gains anything by typing its code.

When a prize has coupon rules, the winner is told: the result panel and the win email add a line such as Conditions: Min spend £60.00 · Shoes only, after your own wording, so nobody is surprised at checkout.

A Fixed product discount prize without coupon rules takes its amount off every item in the cart, which is how WooCommerce treats that type. The Wheel screen says so under the row; choose coupon rules limited to the products you mean.

A free gift. There is no separate prize type for it. Make a coupon limited to the one product and to 1 item, choose it as the coupon rules for a Percentage discount prize of 100, and the winner adds the product to the cart and the code makes it free.

If the coupon you chose is later moved to the bin, deleted, set to draft or made private, that prize cannot be won until you act, the same way a sold-out prize is left out. Handing out its codes on the defaults instead would turn a free gift into 100% off the whole order. The Wheel screen and the Dashboard name the prize straight away, the line under it says the coupon is not published, and the odds on the Wheel screen leave it out. Choose another coupon, remove the chosen one to use the defaults on purpose, or restore or publish the coupon again. Saving the wheel on its own does not bring the prize back.

While it is out, spins land on the other slices. If it was the only prize with odds that could be won, the wheel stops showing on your shop, as a wheel with no odds does, and the page caches it knows (the same list as for the Schedule, below) are emptied so no cached page keeps the popup. The Dashboard then says No prize can be won right now. Restoring or publishing the coupon again brings the wheel back by itself. A No luck slice with a weight does not keep the wheel showing on its own, as when every prize is sold out: a wheel that could only land on No luck is not shown.

This follows the coupon's status whenever WordPress or WooCommerce changes it, from the Coupons screen, the REST API or WP-CLI. A status changed straight in the database is only noticed at the next save of the wheel, but no code is ever made from a coupon that is not published. Only whether that prize can be won is written then: a bulk action or a clean-up task that reaches the coupon while shoppers are winning leaves every prize's stock, and the rest of your settings, as they are at that moment.

Switching a prize to No luck and back keeps its coupon rules and its expiry.

Free shipping prizes#

A free shipping prize, or Also grant free shipping, only removes the delivery charge through a WooCommerce Free shipping method whose Free shipping requires is set to A valid free shipping coupon (or one of the choices that includes a coupon). When no shipping zone has one, or shipping is turned off in WooCommerce, the Wheel screen and the dashboard say so, with a link to the shipping settings.