DeepLinkrs · Affiliate

Reporting a sale

Two integration points. A creator sends a visitor through a tracked link; when that visitor buys, your server tells us. Everything in between — attribution, commission, holding period, statements — is ours.

You will write roughly twenty lines of server code. The only hard requirement is that the second step runs on your server, never in the browser: it is signed with a secret that must never reach a page.

1 · The click

Partners share a DeepLinkrs link. We record the click, then redirect to your site with one extra query parameter:

what your page receives
https://your-shop.example/product/42?dl_cid=3f1c9a2e-7b4d-4e8a-9c21-5d6f0b8e4a17

Store dl_cid the way you already store a UTM — session, cookie, or on the order record. You need it at checkout. It is the only thing that ties a sale to a partner.

Default attribution window is 30 days, configurable per program from 1 to 90.

If dl_cid is missing when the order is placed, still send the postback. We record the sale as unattributed rather than losing it, and the response tells you so. Silence is the one outcome you cannot debug later.

2 · The postback

When an order is confirmed and paid, POST it to us. Server-side, once per order.

POST https://www.deeplinkrs.com/api/affiliate/conversion
{
  "programId":   "prog_7c2a...",      // given to you with the program
  "orderId":     "ORDER-10482",       // yours; also the idempotency key
  "clickId":     "3f1c9a2e-7b4d-4e8a-9c21-5d6f0b8e4a17", // the dl_cid you stored ("" if none)
  "amountCents": 12900,               // integer cents, never 129.00
  "currency":    "CAD",               // must match the program currency
  "ts":          1756400000000,       // Date.now(), milliseconds
  "signature":   "b91f…"              // see below
}

The signature

HMAC-SHA256 over a canonical string, lowercase hex, keyed with your program secret. The fields are joined by newlines, in exactly this order, and the first line names the action:

canonical string
conversion.v1
<programId>
<orderId>
<amountCents>
<currency>
<clickId>
<ts>
Node.js
import { createHmac } from 'node:crypto';

const payload = [
  'conversion.v1',
  programId,
  orderId,
  String(amountCents),   // the string of the integer, not a float
  currency,
  clickId,
  String(ts),
].join('\n');

const signature = createHmac('sha256', PROGRAM_SECRET)
  .update(payload)
  .digest('hex');

Why the first line matters. It binds a signature to one action. Without it, a genuinely signed sale could be replayed against the reversal endpoint and pass verification there. Reversals use reversal.v1 and a different field list, so the two can never be swapped.

ts must be within 5 minutes of our clock, in either direction. Generate it at send time, not when the order was created, or a queued job will be rejected as stale.

3 · What comes back

200 — recorded
{
  "ok": true,
  "conversionId": "9b0e6d14-2c7a-4f3b-8e51-a6d2c9f07b38",
  "commissionCents": 1290,
  "status": "pending",
  "approveAt": 1760288000000
}

A commission is pending until the holding period elapses — 45 days by default, 0 to 120 per program — then becomes approved on its own. That window is your refund window: reverse a sale inside it and nothing was ever owed.

If the click could not be attributed, the same 200 carries an extra field:

{ "ok": true, …, "unattributed": "no-click" }   // or "expired", "wrong-program"

The sale is recorded, no commission is owed. Treat it as success, not as an error.

Sending twice is safe

orderId is the idempotency key. A repeat returns{ "ok": true, "duplicate": true } and changes nothing. Retry freely on timeouts — a network failure mid-request is the normal case, and double-paying a partner is not.

Test sales

An orderId that starts with test_ goes through every check a real sale does (signature, timestamp, currency, attribution) and records nothing. The answer is { "ok": true, "test": true, "recorded": false, "commissionCents": … }. The Setup tab of your dashboard prepares a signed test sale for you and shows the last signed call it received from your shop.

4 · Errors

Every failure is { "ok": false, "error": "…" } with a matching status.

errorhttpwhat to do
bad-signature401Wrong secret, or the canonical string does not match byte for byte.
stale-timestamp401Outside the 5-minute window. Re-sign with a fresh ts and resend.
missing-fields400A required field is absent or empty.
invalid-amount400Not an integer, negative, or above 10 000 000 cents.
invalid-timestamp400ts is not a finite number of milliseconds.
currency-mismatch400Does not match the program currency, which is immutable.
unknown-program404programId does not exist.
program-inactive409The program is still a draft. Paused programs keep accepting sales.
program-frozen402Your DeepLinkrs plan has ended: sales are not recorded until you reactivate PRO.
program-misconfigured503No signing secret on our side. Contact us — do not retry.
rate-limited429Back off and retry.
write-failed500Ours. Retry with the same orderId — it can never be recorded twice.

5 · Refunds and cancellations

Same shape, different endpoint and a different canonical string.

POST /api/affiliate/reverse
{
  "programId": "prog_7c2a…",
  "orderId":   "ORDER-10482",
  "reason":    "refund",        // your own label; it is signed
  "ts":        1756400000000,
  "signature":  "…"            // HMAC over the string below
}

reversal.v1
<programId>
<orderId>
<reason>
<ts>

Before the holding period ends, the commission is simply cancelled. After it has been paid out, we write a negative counter-entry instead of editing the paid line — a statement already sent to a partner must never change retroactively.

unknown-order (404) means we have no conversion under thatorderId. Reversing an order twice answers 200 with duplicate: true. busy-retry (409) means a statement or another reversal is in progress: retry in a few seconds.

6 · Before you go live

Your programId and signing secret are issued when the program is created. The secret is shown once and can be rotated; rotating invalidates the previous one immediately.

DeepLinkrs