Coupon abuse

What you will build

One use of a code per device, with a code cooldown. This is an illustrative application policy, not a default rule that ShieldLabs applies to every customer.

Run the starting application

You need Node.js 22 or later. The starter runs without ShieldLabs keys; the final version needs a registered HTTPS hostname and matching keys. Clone the public tutorial repository, then start this standalone application:

git clone https://github.com/ShieldLabs-ai/use-case-tutorials.git
cd use-case-tutorials
git switch starter
cd coupon-abuse
npm ci --omit=dev
cp .env.example .env
npm run dev

Open http://127.0.0.1:3000. The starter has no ShieldLabs dependency or identification check. Its own SQLite state is separate from every other tutorial.

Add the integration

Stop the starter server. Follow these changes, then run the complete implementation from the final branch.

1. Prepare the keys and HTTPS hostname

The .env copied from starter contains no key entries yet. Add the two lines below with this domain’s real values:

SHIELDLABS_PUBLIC_KEY=your-public-key
SHIELDLABS_API_KEY=sec_your_private_api_key

Register the app’s hostname in Integration > Domains. Put its matching Public Key and Private API Key in the private coupon-abuse/.env as SHIELDLABS_PUBLIC_KEY and SHIELDLABS_API_KEY. Serve this app through HTTPS on that registered hostname. The Private API Key stays on the server; a customer key does not automatically authorize localhost.

2. Identify the action in the browser

The public/index.html page loads the locally served JS SDK. In public/index.js, each action takes a fresh Request ID and sends it with the action:

const requestId = await identification.take();
const data = await postJson('/api/coupons/apply', { code, requestId });

Only the Request ID goes to the server; the browser does not supply the risk result.

3. Verify the identification on the server

server/shieldlabs.js uses @shieldlabs-ai/node and the Private API Key to find that exact Request ID in History. The action route passes it to server/coupons.js, where verifyIdentification(requestId) rejects missing, stale, replayed, automated or unusable checks before this scenario’s rule is applied.

4. Apply the coupon limit rule

This excerpt from server/coupons.js shows the decision’s core:

if (db.prepare('SELECT 1 FROM redemptions WHERE code = ? AND device_id = ?').get(coupon.code, deviceId)) {
  return { success: false, message: `Coupon refused: you already used ${coupon.code}.` };
}

server/coupons.js verifies the identification, then allows one redemption of a code per Device ID. A different code on that device is subject to a one-hour cooldown. The sample code is WELCOME20.

5. Run the completed application

From the repository root, compare the two versions and start the final app:

cd ..
git diff starter origin/final -- coupon-abuse
git switch final
cd coupon-abuse
npm ci --omit=dev
npm start

A fresh clone has the remote origin/final ref even before its local final branch exists. Open the completed app through the registered HTTPS hostname. The Node server listens on 127.0.0.1:3000 behind your reverse proxy.

Follow the integration code

The completed source is in the coupon-abuse application. Read these files in order:

Browser helper: loads the installed SDK, serializes checks and returns a request ID.
Server verification: reads real History, checks the matching ID, rereads delayed results and rejects unusable or replayed checks.
Scenario decision: applies this app’s rule using the verified identification and stores its sample state.

The finished application keeps its browser, server and SQLite state inside this folder. The tests use synthetic History responses; the normal server does not manufacture a successful identification.

Try the completed application

Apply WELCOME20 to the sample cart. The discount appears.
Apply WELCOME20 again with a fresh Request ID on the same device. The app refuses a second redemption.
Try a different available code. The one-hour cooldown prevents immediate code cycling.

Use Reset demo DB with DEMO_ALLOW_RESET=1 to repeat the exercise. These controls are for a disposable demonstration, not production authorization.

Check your result

In DevTools Network, inspect the /api/coupons/apply request and copy its requestId. Inspect each /api/coupons/apply Request ID in History and confirm the same Device ID. The app stores a redemption only for the successful request. Run npm run check and npm test from coupon-abuse to exercise failure cases locally without making more identifications. For a real run, obtain fresh request IDs in the browser and confirm their Device IDs and signals in History. If identification returns HTTP 429, stop and check your account limits before retrying. A cookie change does not prove that the Device ID changed: compare the History rows.

Adapt it to your product

This example is a starting point, not a production-ready authorization system. Bind each action to an authenticated session where appropriate, authorize administration screens, persist state and atomically consume request IDs across all server instances. Review legitimate shared-device behavior before applying a device-based restriction. See Acting on results.

Overview

Runnable examples

Accounts and applications

Payments and rewards

Experience and traffic

Investigate

Accounts

Promotions and rewards

Payments and content

Traffic and experience

What you will build

Run the starting application

Add the integration

Follow the integration code

Try the completed application

Check your result

Adapt it to your product

​What you will build

​Run the starting application

​Add the integration

​Follow the integration code

​Try the completed application

​Check your result

​Adapt it to your product

What you will build

Run the starting application

Add the integration

Follow the integration code

Try the completed application

Check your result

Adapt it to your product