Coupon Abuse

<script type="module">
  const mod = await import(
    'https://cdn.shieldlabs.ai/snippet.js?publicKey=YOUR_PUBLIC_KEY'
  );
  // Signed-in shopper: pass the hashed account id, never a raw email.
  // Guest checkout: use checkAnonymous(undefined, (ip, requestID) => {...}) instead.
  mod.checkAuthenticatedUser('8a9f-hashed-account-id', (ip, requestID) => {
    document.getElementById('shield-request-id').value = requestID;
  });
</script>

<form method="POST" action="/api/apply-coupon">
  <input type="hidden" id="shield-request-id" name="shieldRequestId" />
  <input type="text" name="couponCode" placeholder="Coupon code" />
  <button type="submit">Apply code</button>
</form>

app.post('/api/apply-coupon', async (req, res) => {
  const { accountId, couponCode, shieldRequestId } = req.body;

  // 1. Your own commerce checks first: code exists, in its valid window,
  //    not already marked spent (for single-use codes), within cart rules.
  const coupon = await lookupCoupon(couponCode);
  if (!coupon || !coupon.active) {
    return res.status(409).json({ error: 'Coupon not valid' });
  }
  if (coupon.singleUse && coupon.spent) {
    // A single-use code applied again is reuse on its face — refuse outright.
    return res.status(409).json({ error: 'Coupon already redeemed' });
  }

  // 2. Look up the ShieldLabs result for this redeeming session.
  const shield  = await waitForScore(shieldRequestId, 2000);
  const score   = shield?.score ?? 0;       // 0-100, default 0 if not yet in
  const signals = shield?.signals ?? [];    // explainable: [{ name, weight }]

  // Use the stable detection_flags to tell WHICH signal fired — a 30 from one
  // signal is not a 30 from another. These masking signals are innocent in
  // isolation, so weigh them against the redemption count below.
  const flags  = shield?.detection_flags ?? {};
  const masked = flags.vpn || flags.proxy || flags.tor || flags.private_relay
    || flags.browser_vpn_proxy || flags.anti_detect_browser || flags.datacenter_ip;

  // 3. YOUR code owns the verdict. Branch on the band, not a label string.
  if (score >= 60 || masked) {
    // High band or strong masking on the session applying the code.
    // Hold the discount and require verification before honoring it.
    return res.status(200).json({ requireVerification: true, reason: 'anonymity' });
  }

  // Clean / Low / Medium: carry on to the redemption-count check.
  return countAndDecide(req, res, shield, coupon);
});

curl "https://account.shieldlabs.ai/api/v1/history/device_id/5eb7fd5c-1c5e-4a9f-9b21-7d2e8c0a1234?limit=50" \
  -H "Authorization: Bearer sec_your_private_api_key"

async function redemptionsFromDevice(deviceId) {
  const rows = await shieldHistory('device_id', deviceId, 100);
  // Your own store records which coupon each request_id redeemed. Join the
  // ShieldLabs history (sessions off this device) to your redemption log.
  return countYourRedemptions(rows.map((r) => r.request_id));
}

async function countAndDecide(req, res, shield, coupon) {
  const deviceId   = shield?.device_id;
  const localIp    = shield?.local_ip?.ip;

  // The all-zero DeviceID is "no device", not a clean new one. A JS-disabled
  // or blocked browser returns it with a score of 90 or higher — a shopper that
  // strips JS would dodge the device count, so hold on the score alone.
  const NIL = '00000000-0000-0000-0000-000000000000';
  if (!deviceId || deviceId === NIL) {
    return res.status(200).json({ requireVerification: true, reason: 'no_device' });
  }

  // Count this code's redemptions off this one machine and local network.
  const fromDevice = await redemptionsFromDevice(deviceId);
  const fromLocal  = localIp ? await redemptionsFromLocalIp(localIp, coupon.code) : 0;

  // YOUR_PER_CUSTOMER_LIMIT is your policy (usually 1 for a one-per-customer
  // code). A single-use code already spent was refused upstream in step 3.
  if (fromDevice >= YOUR_PER_CUSTOMER_LIMIT || fromLocal >= YOUR_PER_NETWORK_LIMIT) {
    return res.status(200).json({ requireVerification: true, reason: 'code_already_redeemed_here' });
  }

  // Clear: honor the discount and record the redemption against this device.
  return honorDiscount(req, res, { deviceId, requestId: shield.request_id });
}