# Promotion abuse > Enforce one redemption per device for coupons, referral rewards and free trials, however many accounts or email addresses the device uses. Last updated: 2026-09-17 A promotion meant for one customer, redeemed by one person many times: a first-order discount on ten new accounts, a referral reward for referring yourself, a free trial started again every month. Limits per account or per email address do not help, because accounts and addresses are free. A limit per device does. ## Where to identify | Moment | Tag | Why | | --- | --- | --- | | Applying a coupon or promotion code | `promo:
` | The tag binds the identification to one promotion. |
| Claiming a referral reward | `referral:` | Compare the device with the referrer's. |
| Starting a free trial | `trial-start` | One trial per device. |

## Identify in the client

```ts JavaScript
import { load } from '@fingerly/web-js'

const fingerly = await load({ apiKey: 'fly_pk_us_production_…' })

async function submit() {
  let requestId: string | undefined
  try {
    ({ requestId } = await fingerly.identify({ tag: 'promo:' + code }))
  } catch {
    // Carry on: your server treats a missing request ID as missing evidence.
  }
  await fetch('/api/promotions/redeem', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ code, requestId }) })
}
```

```swift Swift
let requestId = try? await fingerly.identify(tag: "promo:\(code)").requestId
try await api.redeem(code: code, requestId: requestId)
```

```kotlin Kotlin
val requestId = runCatching { fingerly.identify(tag = "promo:$code").requestId }.getOrNull()
api.redeem(code, requestId)
```

## Read the event on your server

Every recipe starts the same way: read the stored event with a secret key, and refuse to trust it unless it belongs to this action, is recent, and has not been used before. Fingerly does not stop a request ID from being read twice, so the one-time check is yours: any store with an atomic "add if absent" works, such as Redis `SET` with `NX` and a ten-minute expiry.

```ts Node.js
// fingerly.server.ts
import { load, FingerlyAPIError } from '@fingerly/node'

const fingerly = load({ secretKey: process.env.FINGERLY_SECRET_KEY! })
const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms))

async function readEvent(requestId: string) {
  for (let attempt = 1; ; attempt++) {
    try {
      return await fingerly.events.get(requestId)
    } catch (error) {
      const status = error instanceof FingerlyAPIError ? error.status : undefined
      if (status === 404 && attempt < 4) await sleep(attempt * 250)   // not readable yet
      else if (status === 404 || status === 422) return null
      else throw error
    }
  }
}

/**
 * The stored event behind a request ID, or null when there is nothing to
 * trust: no ID, an unknown ID, another action's tag, too old, or used before.
 */
export async function verifiedEvent(requestId: unknown, tag: string, maxAgeMs = 2 * 60 * 1000) {
  if (typeof requestId !== 'string' || requestId === '') return null

  const event = await readEvent(requestId)
  if (!event || event.tag !== tag) return null
  if (Date.now() - Date.parse(event.occurred_at) > maxAgeMs) return null
  if (!(await usedRequestIds.add(event.request_id))) return null   // your store: true only the first time

  return event
}

/** Whether any of these signal groups fired. */
export const fired = (event: { triggers: Array<{ signal: string }> }, ...groups: string[]) =>
  event.triggers.some((trigger) => groups.includes(trigger.signal))
```

```python Python
# fingerly_server.py
import os
import time
from datetime import datetime, timedelta, timezone
from fingerly import Fingerly, FingerlyAPIError

fingerly = Fingerly(secret_key=os.environ["FINGERLY_SECRET_KEY"])

def _read_event(request_id):
    for attempt in range(1, 5):
        try:
            return fingerly.events.get(request_id)
        except FingerlyAPIError as error:
            if error.status == 404 and attempt < 4:
                time.sleep(attempt * 0.25)  # not readable yet
            elif error.status in (404, 422):
                return None
            else:
                raise

def verified_event(request_id, tag, max_age=timedelta(minutes=2)):
    """The stored event behind a request ID, or None when there is nothing to trust."""
    if not isinstance(request_id, str) or not request_id:
        return None

    event = _read_event(request_id)
    if event is None or event.tag != tag:
        return None
    if datetime.now(timezone.utc) - event.occurred_at > max_age:
        return None
    if not used_request_ids.add(event.request_id):  # your store: True only the first time
        return None
    return event

def fired(event, *groups):
    """Whether any of these signal groups fired."""
    return any(trigger.signal in groups for trigger in event.triggers)
```

`verifiedEvent` returns nothing when the client could not identify the visitor at all. Treat that as missing evidence: the policies below add friction a real customer can pass, rather than refusing outright.

## Decide

Enforce the limit in your database with a unique index on the promotion and the visitor ID, so two redemptions racing each other cannot both succeed.

```ts Node.js
import { fired, verifiedEvent } from './fingerly.server'

export async function redeem(accountId: string, code: string, requestId: unknown) {
  const event = await verifiedEvent(requestId, 'promo:' + code)

  // A promotion is optional: without evidence, ask for more before applying it.
  if (!event || fired(event, 'fingerprint_suppressed')) return 'verify'
  if (event.suspect_level === 'high') return 'refuse'

  // unique index on (code, visitor_id)
  const inserted = await redemptions.insertIfAbsent({ code, visitorId: event.visitor_id, accountId })
  return inserted ? 'apply' : 'already-redeemed'
}

export async function isSelfReferral(referrerId: string, requestId: unknown) {
  const event = await verifiedEvent(requestId, 'referral:' + referrerId)
  if (!event) return true   // no evidence, no reward
  return accounts.hasUsedDevice(referrerId, event.visitor_id)
}
```

```python Python
from fingerly_server import fired, verified_event

def redeem(account_id, code, request_id):
    event = verified_event(request_id, f"promo:{code}")

    # A promotion is optional: without evidence, ask for more before applying it.
    if event is None or fired(event, "fingerprint_suppressed"):
        return "verify"
    if event.suspect_level == "high":
        return "refuse"

    # unique index on (code, visitor_id)
    inserted = redemptions.insert_if_absent(code=code, visitor_id=event.visitor_id, account_id=account_id)
    return "apply" if inserted else "already-redeemed"

def is_self_referral(referrer_id, request_id):
    event = verified_event(request_id, f"referral:{referrer_id}")
    if event is None:
        return True  # no evidence, no reward
    return accounts.has_used_device(referrer_id, event.visitor_id)
```

## A starting policy

| Situation | Action |
| --- | --- |
| The device already redeemed this promotion | Refuse the discount, and say it has already been used on this device. |
| A referral where the new customer's device has been used by the referrer | Create the account, but pay no reward. |
| `high` level | Refuse the promotion. |
| `fingerprint_suppressed` fired, or no usable identification | Ask for verification, such as a phone number, before applying it. |
| Otherwise | Apply it. |

## Signals that matter here

| Group | Why it matters for promotions |
| --- | --- |
| `fingerprint_suppressed` | The device hides enough to get a new visitor ID every time, which would defeat a per-device limit. |
| `device_farm`, `android_emulator`, `ios_simulator`, `cloned_app` | Many "devices" that are really one person's setup. |
| `bot` | Redemptions scripted at scale. |
| `residential_proxy`, `vpn` | Used to make repeated sign-ups look like different households. |

> **Tip:** Tell customers the limit is per device in the promotion's terms. A real customer who is refused then knows why.

## Roll it out

- **Observe first.** Run the check and log the decision it would have made, next to what actually happened, for a week or two.
- **Tune.** Look at the sessions the policy would have stopped in **Identification > Events**, and adjust [risk weights](https://docs.fingerly.io/docs/risk-weights) and the thresholds in your own code until they match what you see.
- **Enforce gradually.** Turn on the friction a real customer can pass before the outright blocks.

- [Sign-up abuse](https://docs.fingerly.io/docs/use-cases/sign-up-abuse): Stop the accounts before they redeem.
- [Payment fraud](https://docs.fingerly.io/docs/use-cases/payment-fraud): Protect the order the promotion applies to.