Guides/Winning Moments

How Winning Moments work

Every LuckLogic campaign decides its winners the same way. This guide explains the mechanic from first principles: what a Winning Moment is, what happens when nobody is entering, what happens when everybody is, and why two entries can never win the same prize.

What is a Winning Moment?

A Winning Moment is a hidden timestamp inside a prize tier's window. When a campaign is activated, LuckLogic generates one moment for every prize: a tier with 5,000 free drinks gets 5,000 moments, a tier with one trip gets one. The schedule is written once, stored server-side, and never returned by any API.

Prizes are released at these predetermined moments throughout the campaign rather than being encoded into individual printed codes. The pack does not know whether it will win. Neither does the print file, the warehouse or the agency. The outcome exists only at the instant an entry is processed.

How the moments are placed is a per-tier choice. even puts one moment in each equal slice of the window, so prizes flow steadily. late_stage spreads them evenly over the last 30% of the window, which keeps a headline prize out of play until the end. uniform draws each moment independently at random. A tier can also have its own window inside the campaign, for example phones from week five onwards.

Codes are entries, not winning tickets

A valid code establishes eligibility to enter. That is all it does. It proves the consumer has a pack, it can be used once, and it is checked against the campaign's rules: is the campaign active, has this participant reached their limit, is the code unused. If everything passes, the entry is processed and the outcome is determined right then, by whether a Winning Moment is open.

This is why a leaked print file, a photographed carton or an insider at the printer reveals nothing. There is nothing in a code to reveal.

The basic flow

  1. A Winning Moment's timestamp passes. The moment is now open.
  2. The next eligible entry arrives, from the API, the widget or the hosted page.
  3. The prize is allocated to that entry atomically. The moment is now claimed.
  4. A claim is created with its own token, status and expiry. The consumer is told they have won.

The entry that wins is the first one processed after the moment opens, not the first one submitted that day, that hour, or that minute. If no moment is open when an entry is processed, the entry loses and the code is consumed. That is the whole rule.

What happens during quiet periods?

A moment that opens during a quiet period stays open. If several open before the next entry arrives, they queue. Each valid entry claims at most one prize, always the oldest open moment first, so the next few entrants drain the backlog one prize each.

Nothing is lost overnight. A campaign with 60 moments a day that gets no entries between midnight and seven will hand roughly 18 prizes to the first 18 valid entries of the morning. The brand's prize budget is spent at the rate the schedule says, not at the rate consumers happen to show up.

Do Winning Moments expire?

  • Open moments do not expire during the campaign. They wait for the next valid entry.
  • A tier can carry a claim deadline. Once it passes, the tier stops awarding, even if moments are still open, because a prize nobody can collect should not be won.
  • Those moments stay unawarded. They are not reassigned to another tier.
  • Anything unawarded when the campaign ends is reported in the campaign's stats, per tier, so the brand knows exactly how much prize inventory was never released.

Separately from the moment, every claim has an expiry: the winner must collect or be approved within the tier's claim period, after which the claim expires and shows up as such in reconciliation. The moment was awarded; the prize simply was not collected.

Traffic spikes

A launch-day spike cannot drain prizes intended for the whole campaign. Moments are timestamps, and a timestamp that has not arrived cannot be won no matter how many entries come in. With 5,000 free drinks spread evenly over twelve weeks, about 60 moments open on day one. A hundred thousand entries that day can win about 60 drinks, and the entrants on day 84 have the same 60 waiting for them.

The opposite is also true: a spike does not waste prizes. If a moment is open, the spike claims it; if not, the spike loses. Prize release follows the schedule, and consumer traffic only decides who gets each prize, never how many are given out.

Before activating, POST /v1/campaigns/{id}/simulate runs the schedule against an expected number of entries in a steady, front-loaded or back-loaded pattern and reports prizes won per tier, prizes left at the end and the overall odds. It uses fresh random schedules, so it never reveals the real one.

Concurrency

Two entries can arrive in the same millisecond. Two different consumers can type different valid codes at the exact instant the campaign's only trip opens. One tab can submit the same code twice. None of these can produce two winners for one prize.

Each redemption runs as a single transaction in which the code, the participant's limit and the oldest open moment are each taken exclusively, in a fixed order. A second request for the same code waits for the first and then learns the code is already used. Two requests for the same open moment cannot both hold it: one claims it and the other moves on to the next open moment, or loses if there is none. The only clock consulted is the database's own, so no two servers can disagree about whether a moment has opened.

Retries are handled separately. A request that times out and is sent again with the same Idempotency-Key gets the original answer rather than a second entry. The duplicate prize awards guide walks through each race in detail.

Example timeline

One tier, three moments, a quiet late morning and a busy lunch hour:

  1. Moment A opensopen
  2. Entry arrives. It wins A.win
  3. Moment B opens. No entries arrive.open
  4. Quiet period. B waits.
  5. Moment C opens. B and C are both open; B is older.open
  6. First entry of the lunch rush. It wins B.win
  7. Second entry. It wins C.win
  8. Third entry. Nothing is open. It loses.lose

The 10:03 entry won because A was open. The entrants between 10:03 and 12:15 lost, not because of bad luck in a draw, but because nothing was open. B waited an hour and fifteen minutes and was not lost. The third lunch entry lost because the two open prizes had just gone, and the next one will go to whoever is processed first after the next moment opens.

Where this is in the API

  • Tiers, quantities, distributions, windows and claim deadlines are set when you create a campaign.
  • The schedule is generated on activation.
  • Each redemption returns win or lose, the prize tier and a claim token.
  • Per-tier stats report prizes won, claims by status, and moments still open at the end (the pending bucket, which is the unawarded count). See Campaigns in the API reference.
  • In the Sandbox, force-win makes the next valid code win a chosen tier so you can test the win path.
Try Winning Moments in the Sandbox Read the Docs

Keep reading

Preventing duplicate prize awardsThe races, and what stops each one. Scoping a prize promotionTiers, quantities, windows and deadlines to decide up front. For AgenciesWhat LuckLogic handles and what stays with you.