> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shieldlabs.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# First-order promotion

> Run the standalone promo-abuse app and compare its starter and final versions.

## What you will build

One first-order discount per device. 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](https://github.com/ShieldLabs-ai/use-case-tutorials), then start this standalone application:

```sh theme={null}
git clone https://github.com/ShieldLabs-ai/use-case-tutorials.git
cd use-case-tutorials
git switch starter
cd promo-abuse
npm ci --omit=dev
cp .env.example .env
npm run dev
```

Open [http://127.0.0.1:3000](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.

> [!NOTE]
>
> The completed application uses browser SDK `1.1.0` and Node SDK `1.3.0`. Its browser helper reads `result.identificationId`; `requestId` is the tutorial application's own submitted field. Its server reads a domain-scoped identification card and requires available risk and signal states before applying the action policy. An unavailable state is not a clean score or a negative signal. See [History](https://docs.shieldlabs.ai/api/history.md) for the response contract.

## Add the integration

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

**1. 1. Prepare the keys and HTTPS hostname**

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

```dotenv theme={null}
SHIELDLABS_PUBLIC_KEY=your-public-key
SHIELDLABS_API_KEY=sec_your_private_api_key
SHIELDLABS_DOMAIN_ID=your-domain-uuid
```

Get the public domain UUID for this hostname using `GET /api/v1/domains` with the Private API Key, or OAuth MCP `shieldlabs_list_domains`. Copy its `id` into `SHIELDLABS_DOMAIN_ID`; do not substitute the hostname.

Register the app's hostname in **Integration > Domains**. Put its matching Public Key and Private API Key in the private `promo-abuse/.env` as `SHIELDLABS_PUBLIC_KEY` and `SHIELDLABS_API_KEY`. Resolve that hostname through `GET /api/v1/domains` with the Private API Key, or OAuth MCP `shieldlabs_list_domains`, and set its public UUID as `SHIELDLABS_DOMAIN_ID`. 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. 2. Identify the action in the browser**

The protected page loads the locally served JS SDK. In `public/index.js`, each action takes a fresh Identification ID and sends it with the action. `requestId` is this application's payload field; the browser helper reads `result.identificationId` from the SDK:

```js theme={null}
const requestId = await identification.take();
const data = await postJson('/api/checkout', { email, requestId });
```

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

**3. 3. Verify the identification on the server**

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

**4. 4. Apply the first order promo rule**

This excerpt from [`server/orders.js`](https://github.com/ShieldLabs-ai/use-case-tutorials/blob/1ce18350ce516183aea0bf1ea848fabf625f9cfe/promo-abuse/server/orders.js) shows the decision's core:

```js theme={null}
const hasOrderedBefore = Boolean(db.prepare('SELECT 1 FROM orders WHERE device_id = ?').get(deviceId));
const subtotalCents = toCents(SUBTOTAL);
const discountCents = hasOrderedBefore ? 0 : Math.round((subtotalCents * FIRST_ORDER_DISCOUNT_PERCENT) / 100);
```

`server/orders.js` decides the 20% first-order discount using the verified Device ID, not the browser's promotional hint cookie or checkout email.

**5. 5. Run the completed application**

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

```sh theme={null}
cd ..
git diff starter 1ce18350ce516183aea0bf1ea848fabf625f9cfe -- promo-abuse
git switch --detach 1ce18350ce516183aea0bf1ea848fabf625f9cfe
cd promo-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 [promo-abuse application](https://github.com/ShieldLabs-ai/use-case-tutorials/tree/1ce18350ce516183aea0bf1ea848fabf625f9cfe/promo-abuse). Read these files in order:

1. [Browser helper](https://github.com/ShieldLabs-ai/use-case-tutorials/blob/1ce18350ce516183aea0bf1ea848fabf625f9cfe/promo-abuse/public/shieldlabs.js): loads the installed SDK, serializes checks and returns an Identification ID.
2. [Server verification](https://github.com/ShieldLabs-ai/use-case-tutorials/blob/1ce18350ce516183aea0bf1ea848fabf625f9cfe/promo-abuse/server/shieldlabs.js): reads real History, checks the matching ID, waits within a bounded budget for pending results and rejects unusable or replayed checks.
3. [Scenario decision](https://github.com/ShieldLabs-ai/use-case-tutorials/blob/1ce18350ce516183aea0bf1ea848fabf625f9cfe/promo-abuse/server/orders.js): applies this app's rule using the verified identification and stores its sample state.

The [finished application](https://github.com/ShieldLabs-ai/use-case-tutorials/tree/1ce18350ce516183aea0bf1ea848fabf625f9cfe/promo-abuse) 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

1. Place a simulated order with one invented email. The first checkout receives 20% off.
2. Place another simulated order with a different email on the same device. The checkout succeeds at full price.
3. Compare the two displayed totals; clearing the hint cookie does not reset server-side eligibility.

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/checkout request and copy its `requestId`. The two checkout Identification IDs should resolve to the same Device ID in History. The second order has zero discount in the local order record. Run `npm run check` and `npm test` from `promo-abuse` to exercise failure cases locally without making more identifications.

For a real run, obtain fresh Identification IDs in the browser and confirm their Device IDs and signals in History. If identification returns HTTP 429, stop and respect the returned retry guidance; the status alone does not establish exhausted plan volume. 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 Identification IDs across all server instances. Review legitimate shared-device behavior before applying a device-based restriction. See [Acting on results](https://docs.shieldlabs.ai/guides/acting-on-risk-score.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.