Games in Digital Channels

Use this guide when a web experience, mobile app, kiosk, e-commerce frontend, or any customer-facing digital channel needs to display and run Loyal Guru games such as Scratch & Win or Spin the Wheel.

Core endpoints

Endpoint	Use it for
GET /games	List active game campaigns available to the integration context.
GET /games/{id}	Read a specific game campaign.
POST /games/{id}/play	Execute one play and receive the outcome.
GET /customers/{id}/vouchers	Read vouchers generated by game prizes, when the prize creates one.

Visibility, play, and prize flow

Choosing the visibility model

Games can be made available through customer conditions or through personalized delivery. Choose the model based on what you need to segment.

Model	How it behaves	Use when
Customer conditions	The game is available whenever the customer currently matches the configured attributes.	You have stable profile attributes or external segments stored as customer attributes.
Targeted Delivery	The game is sent to a selected audience. Re-send the campaign if you need to refresh who receives it.	You need a delivery, communication, or audience snapshot.
Audience based on purchase history	The audience should be built from historical carts, purchases, or campaign behavior.	Segmentation depends on transaction history or calculated attributes.

Important distinctions:

• Customer conditions control whether the game is visible or playable for customers with matching attributes.
• Targeted Delivery creates a personalized assignment and communication flow.
• Play conditions decide whether the customer can view/play; they do not decide which prize the customer wins.
• Game limits control plays or views; they do not mean "maximum wins" unless the prize pool/configuration defines that behavior.

Play outcome

POST /games/{id}/play returns the result of the play. The app should render the animation and final state from the response provided by the backend. If the outcome grants a voucher, the app can also refresh GET /customers/{id}/vouchers to show the newly assigned benefit.

Digital channel rendering checklist

• Do not expose Loyal Guru API credentials in the frontend; call through backend middleware.
• Cache game configuration only briefly; availability, limits, and prize pools can change.
• Render the "already played" or "limit reached" state gracefully.
• Separate the visual animation from the server-side play result. The server response decides whether the customer won.
• If a prize creates a voucher, show the code, validity, and redemption conditions only after the successful play response.

Troubleshooting

Symptom	What to check
Game does not appear	Customer conditions, targeted assignment, active dates, channel/app cache, and customer identity.
Customer can see but cannot play	Play limits, play conditions, customer status, and whether the game has already been played.
Customer plays but never wins	Prize pool configuration, probability, stock, and whether the prize is still active.
Prize is won but not usable at checkout	Voucher assignment, voucher status, campaign validity, store/product restrictions, and checkout coupon flow.