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:
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.
{
"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:
conversion.v1 <programId> <orderId> <amountCents> <currency> <clickId> <ts>
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
{
"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.
| error | http | what to do |
|---|---|---|
| bad-signature | 401 | Wrong secret, or the canonical string does not match byte for byte. |
| stale-timestamp | 401 | Outside the 5-minute window. Re-sign with a fresh ts and resend. |
| missing-fields | 400 | A required field is absent or empty. |
| invalid-amount | 400 | Not an integer, negative, or above 10 000 000 cents. |
| invalid-timestamp | 400 | ts is not a finite number of milliseconds. |
| currency-mismatch | 400 | Does not match the program currency, which is immutable. |
| unknown-program | 404 | programId does not exist. |
| program-inactive | 409 | The program is still a draft. Paused programs keep accepting sales. |
| program-frozen | 402 | Your DeepLinkrs plan has ended: sales are not recorded until you reactivate PRO. |
| program-misconfigured | 503 | No signing secret on our side. Contact us — do not retry. |
| rate-limited | 429 | Back off and retry. |
| write-failed | 500 | Ours. Retry with the same orderId — it can never be recorded twice. |
5 · Refunds and cancellations
Same shape, different endpoint and a different canonical string.
{
"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
- 01The secret lives in your server environment. It is never in a page, a bundle, or a repository.
- 02The postback fires on payment confirmed, not on order created. Reporting unpaid carts inflates what you owe.
- 03Amounts are integer cents.
129.00and12900are different signatures and different money. - 04The call is queued and retried. Your checkout must never wait on us, and never fail because of us.
- 05
dl_cidsurvives your checkout — including guest flows, and any redirect through a payment provider. - 06You send a refund reversal. Without it, you pay commission on money you gave back.
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.