Complete brand setup guide — every tab, every field

Who this guide is for

You’re a brand admin setting up the affiliate program for the first time. You’re going to:

1. Configure the program (6 tabs in one modal, ~10 min)
2. Recruit your first 5–10 affiliate influencers
3. Connect your purchase events so conversions show up automatically
4. Monitor the first week, calibrate fraud thresholds against real traffic

You don’t need a developer for steps 1–2. Step 3 has a developer-free path (JS pixel or Shopify webhook); the server-side postback path needs a developer once.

---

Before you start

You need:

• A Company workspace with at least one brand inside it (Brands → Add brand if you don’t have one yet).
• A destination URL the affiliate link should send buyers to. Usually your storefront homepage, but it can be a category page, a landing page, or a product page.
• A rough idea of the commission rate you can sustain. Most brands start at 10% of net sale. We’ll explain how to think about this below.
• A brand admin user with settings:edit permission on the brand. Workspace owners + admins have this by default.

You do NOT need: a Shopify store, a developer on day one, a marketing team, or any prior affiliate experience.

---

Stage 1 — Configure the program

Path: /company/affiliate/settings → Click Edit on your brand row → 6-tab modal opens.

The Per-brand setup table with each brand listed and an Edit button on the right.

The modal has 6 tabs. We’ll walk through each one in order. You can save partial progress at any tab — the form remembers state.

Tab 1 — General

This is the only tab where you MUST fill something. Everything else is optional polish.

General tab: Enable toggle, default destination URL, commission %, cookie days, holdback days, code prefix, tracking methods, tax entity.

Field	What it does	Recommendation
Enable affiliate program	Turns the whole thing on or off. When off, links don’t track, postbacks return 401.	Flip ON.
Default destination URL	Where every affiliate link sends users when they click. Influencers can override per-link, but most use this default.	https://yourstore.com (your storefront homepage).
Default commission %	The base rate every conversion earns when no tier or per-SKU override matches.	10% for most retail. 15% for high-margin services / digital goods. 20%+ if you have <30% COGS.
Cookie window (days)	How long after a click we still attribute a purchase to that influencer.	30 days is industry standard. Use shorter (7 days) only for impulse-buy items.
Holdback days	How many days a conversion sits in “pending” before auto-approving for payout. Buys you time to catch refunds.	14 days if you have a 14-day return policy. 30 days if returns can stretch.
Code prefix	The first 2–8 letters of every influencer’s discount code (e.g. NIKE → NIKE-ABCD1234). Leave blank to disable discount codes entirely.	Set it to your brand short code. Empty = you’ll lose attribution on shoppers who paste a code without clicking the link.
Tracking methods	Which methods this brand uses. Check all that apply: postback, pixel, shopify, manual.	Check postback + pixel as a starting pair. Add shopify later if you’re on Shopify.
Tax entity (optional)	The legal entity that pays the affiliate commissions. Shown to creators in their tax summary.	Your registered business name.

Click Save at the bottom. The program is now LIVE — but no one has links yet, so nothing will happen until Stage 2.

Tab 2 — Policy

These settings shape what happens AROUND a conversion. Not required for first launch but worth setting before you go public.

Policy tab: refund policy, FTC disclosure toggle, content approval toggle, currency policy.

Field	What it does
Refund policy	proportional = if the customer refunds half the order, half the commission is clawed back. full_clawback = any partial refund claws back the whole commission. Most brands pick proportional.
Require FTC disclosure	When ON, your public influencer-facing terms include the FTC #ad / disclosure requirement and we surface it in their content guidance. Required for US-targeting brands.
Require content approval	When ON, every piece of content the creator publishes must be approved by you before going live. Slows things down significantly. Default OFF unless you’re in regulated verticals (alcohol, finance, pharma).
Currency policy	source (recommended) keeps the conversion in the buyer’s currency. brand_wallet converts to your wallet currency at our mid-market rate. usd / eur force a single currency.

Tab 3 — Commission tiers (incl. per-product rates)

This is where you make the rate ladder more sophisticated than a single number. You can skip this tab on day one — the default rate from the General tab applies to everyone.

When to come back here:

• You want to reward top performers with a higher rate (a tier ladder)
• You sell products with very different margins and the same rate doesn’t fit all

Commission tiers tab: tier ladder rows (min sales / pct / name) with Add tier button.

Volume tiers (the ladder)

A tier ladder reads: “After this influencer hits N sales, raise their rate to X%.”

Click Add tier. Each row has:

• Min sales — sales count this tier kicks in at
• Pct % — the new rate
• Name (optional) — display label like “silver”, “gold”, “platinum”

Example ladder:

Min sales 0   → 10%  (default tier, also covered by General tab)
Min sales 10  → 12%  (bronze)
Min sales 50  → 15%  (silver)
Min sales 200 → 20%  (gold)

The influencer always earns the highest tier they qualify for at the moment of each sale.

Per-product rates (the new feature)

Below the tier ladder, the Per-product rates section lets you set a different rate per product SKU. This is most useful when your catalog has mixed margins.

Per-product rates: free-text Product name + auto-derived “Postback SKU” hint (monospace, gray) + Pct %.

Click Add product rate. Each row has:

• Product name — your human-readable label (e.g. List Outreach, Premium Subscription). Free text.
• Postback SKU — auto-derived from the name (lowercased, alnum + underscores). This is the string your postback / pixel / webhook must send in skus[] for the rate to apply. Once you save, the SKU locks — renaming the product later won’t break already-integrated postbacks.
• Pct % — the rate for this specific product.

Example:

List Outreach              → list_outreach              → 15%
Premium Subscription       → premium_subscription       → 25%

Precedence order (most specific wins):

1. Per-influencer custom rate (set by Keepface staff on request — email [email protected] if you want a VIP rate for a specific creator)
2. Per-product rate (this section) ← wins over tier ladder
3. Tier ladder
4. Default commission % (General tab)

Critical: the Postback SKU value is what your purchase event must pass in skus[]. Copy it from the hint shown under the name input.

Tab 4 — Restrictions & fraud

These are the “what NOT to commission” rules.

Restrictions & fraud tab: geo allow-list, excluded SKUs/categories textareas, per-sale cap, velocity caps, self-purchase block toggle.

Field	What it does	When to use
Geo allow-list	Two-letter country codes (US, GB, AZ…), one per line. Only conversions from these countries count.	When you can only ship/sell in specific markets. Leave empty = all countries.
Excluded SKUs	SKUs that don’t earn commission, one per line.	Mark your sale/clearance items here so you don’t pay commission on already-discounted units.
Excluded categories	Category names that don’t count.	”gift_cards”, “clearance”, “wholesale_bundle”.
Commission cap per sale	Maximum dollar amount a single conversion can earn (caps abuse on huge orders). 0 = no cap.	$50–$200 depending on your average order value.
Velocity per IP / hour	Anti-fraud — max conversions from the same IP in 60 min.	Default 10. Lower if you’re worried about a creator running their link via friends’ computers.
Velocity per influencer / hour	Max conversions per affiliate per 60 min.	Default 50. Lower if you’ve had abuse before.
Self-purchase block	When ON, conversions where the buyer’s email matches the affiliate’s email get auto-rejected.	Recommended ON.

Tab 5 — Integration

This is where you get the API credentials your developer (or you, copy-pasting from our docs) needs to send purchase events to us.

Integration tab: postback URL (read-only), HMAC secret with Rotate button, Shopify webhook URL+secret, allowed pixel origins, tracking subdomain CNAME.

Field	What it does	Recommendation
Postback URL	The URL your backend POSTs to. Brand-specific path.	Read-only — auto-filled. Copy this to your backend integration.
HMAC secret	The shared secret you sign every postback with. Click Rotate secret to mint a new one (existing secret remains valid for 24h to allow a no-downtime swap).	Copy this to your backend env vars. NEVER commit it.
Shopify webhook URL	Use this in Shopify Admin → Settings → Notifications → Webhooks → “Order paid”.	Only if you’re on Shopify.
Shopify webhook secret	Paste here the secret Shopify auto-generates for each webhook subscription.	Only if you’re on Shopify.
Allowed pixel origins	Hostnames (one per line) that can POST to our JS pixel. Wildcards: *.yourstore.com.	Only if you use the JS pixel.
Tracking subdomain (CNAME)	A subdomain on your domain that we accept affiliate clicks on (e.g. track.yourstore.com).	Optional. Brand-name URLs convert ~5% better than kpfc.link.

We’ll walk through each of these integration paths in Stage 4 below.

Tab 6 — Public page

The public-facing recruitment page where influencers discover your program and apply.

Public page tab: Auto-approve members radio + “Open editor” link to /company/affiliate/page.

Field	What it does
Auto-approve members	When ON, every influencer who applies gets a link minted automatically. When OFF, applications go to a queue you approve manually from /company/affiliate/members.
Editor link	Opens the rich page editor at /company/affiliate/page where you set the logo, commission promise, FAQ, and a list of approved post examples.

If you fill the Public page editor, your program lives at https://keepface.com/affiliate/<your-brand-slug> and influencers can self-apply.

If you leave it blank, the program is invite-only — you must directly invite each affiliate.

---

Stage 2 — Recruit your first influencers

You have three ways to add affiliates to your program.

Path A — Self-signup via public landing (lowest effort)

If you filled out the Public page tab, your program has a public URL:

https://keepface.com/affiliate/<your-brand-slug>

Share this URL on:

• Your existing social channels (“become an affiliate”)
• Your email list to past customers / current creator partners
• The Keepface marketplace (listed automatically if you opted in)

Each influencer who clicks → reads the program → clicks Apply:

• If auto_approve_members=true → link minted instantly, they see it on their dashboard
• If auto_approve_members=false → application sits in your review queue → approve from /company/affiliate/members

The public landing page at /affiliate/<brand-slug> — hero image, commission promise, FAQ, Apply button.

Path B — Direct invite from your brand workspace

Use this when you have a specific creator in mind.

Path: /company/affiliate/members → click Invite influencer.

Coming soon: The dedicated invite UI on /company/affiliate/members is rolling out. For now, use the API mint flow below or have influencers self-apply via your public landing page.

You can invite by:

• Email — sends them a signup link + onboarding
• Existing Keepface user — pick from the marketplace (autocomplete by name / handle)
• Bulk CSV — upload 100+ at once

After invite:

• They get an email + WhatsApp + Telegram notification (whichever channels we have on file)
• They land on /influencer/affiliate/invitations and click Accept
• Link mints, you both see them in your respective dashboards

Path C — API mint (for developers / migrations)

If you’re migrating from another affiliate platform and have a list of creators with their existing tokens you want to preserve, use:

POST /api/v2/admin/affiliate/links/mint
{
  "brand_id": 96,
  "influencer_id": 15374,
  "custom_token": "OPTIONAL-LEGACY-TOKEN",   // omit to let us generate
  "custom_rate_pct": 18                       // optional per-influencer VIP rate
}

See API reference for the full spec.

What every influencer gets

Once a link is minted, the influencer sees this on their dashboard at /influencer/affiliate#my-links — one card per brand they’re enrolled in, with the short link, destination, lifetime clicks, conversions, earnings, and a Copy button:

Brand:     Your Brand
Token:     e6T5ynEd
Short URL: https://kpfc.link/e6T5ynEd
Long URL:  https://yourstore.com?kf_aff=e6T5ynEd
Clicks:    127
Sales:     12
Earnings:  $30.00 KPC

They share the short URL wherever they post.

---

Stage 3 — How click tracking works (no code required)

This entire stage runs on the Keepface edge — you don’t write or deploy anything. We’re documenting it so you understand what’s happening.

1. Influencer shares       https://kpfc.link/e6T5ynEd
                                 ↓
2. User clicks the link
                                 ↓
3. Cloudflare Worker resolves
   - Looks up token → brand_id, destination_url
   - Fraud filter: drop CF bot-score > 30, drop datacenter ASNs,
     drop if country in your geo deny list
   - GDPR: if kf_consent=denied cookie present, skip cookie + redirect
   - Sets kf_aff=e6T5ynEd; Domain=.keepface.com; Max-Age=2592000; SameSite=Lax
                                 ↓
4. 302 redirect → your destination URL with ?kf_aff=e6T5ynEd appended
                                 ↓
5. User browses your site (cookie persists across pages)
                                 ↓
6. User completes a purchase → Stage 4 fires

What you need to know

• Cookie scope is .keepface.com by default. Set up a tracking subdomain CNAME (Integration tab) to scope cookies to your own domain instead.
• Cookie lifetime is whatever you set in Cookie window (default 30 days). Last-touch wins — if the same user later clicks a different affiliate’s link, the second cookie overwrites the first.
• Fraud at click time: the Worker drops obvious bots and datacenter clicks BEFORE setting a cookie, so your conversion pool stays clean.
• No cookie, no commission: if a user has kf_consent=denied (GDPR), they can still buy from you — they just won’t be attributed to any affiliate.

---

Stage 4 — Wire your purchase events (the one developer task)

When a sale completes on your site, you need to tell Keepface. There are three ways to do this. You only need ONE — pick the easiest path for your stack.

Decision tree

Do you sell on Shopify?
├── YES → Use Shopify webhook (10 min, no code)
└── NO →
    │
    Do you have a developer + want bulletproof refund tracking?
    ├── YES → Server-side postback (HMAC, ~30 min)
    └── NO  → JS pixel (5 min, copy/paste)

Method 1 — Server-side postback (recommended)

When the order completes on your backend (after payment confirmation), POST to:

POST https://api.keepface.ai/api/v2/affiliate/postback/{your_brand_id}

With headers:

Content-Type: application/json
X-KF-Signature: sha256=<hmac>
X-KF-Timestamp: <unix_timestamp_in_seconds>

And body:

{
  "affiliate_token": "<value of kf_aff cookie>",
  "order_id": "ord_12345",
  "currency": "USD",
  "gross_amount_minor": 2500,
  "skus": ["list_outreach"],
  "customer_email": "[email protected]",
  "customer_country": "US",
  "customer_ip": "203.0.113.5"
}

Where <hmac> is the lowercase hex-encoded HMAC-SHA256 of <timestamp>.<raw_body> with your HMAC secret as the key.

Node.js implementation:

import crypto from 'crypto';

async function trackConversion(order, kfAffCookie) {
  const body = JSON.stringify({
    affiliate_token: kfAffCookie,
    order_id: order.id,
    currency: order.currency,
    gross_amount_minor: Math.round(order.total * 100),
    skus: order.line_items.map(i => i.sku),
    customer_email: order.customer.email,
    customer_country: order.shipping_address.country_code,
    customer_ip: order.client_ip,
  });
  const ts = Math.floor(Date.now() / 1000);
  const sig = crypto
    .createHmac('sha256', process.env.KEEPFACE_HMAC_SECRET)
    .update(`${ts}.${body}`)
    .digest('hex');

  const r = await fetch(
    `https://api.keepface.ai/api/v2/affiliate/postback/${process.env.KEEPFACE_BRAND_ID}`,
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'X-KF-Signature': `sha256=${sig}`,
        'X-KF-Timestamp': String(ts),
      },
      body,
    }
  );
  if (!r.ok) {
    // Log and don't block checkout — affiliate is supplementary
    console.warn('keepface postback failed', r.status, await r.text());
  }
}

PHP / Python / cURL recipes + refund postback shape: see Postback HMAC integration.

Why this is “best”:

• HMAC + timestamp = anti-replay, anti-tamper
• Server-to-server = no ad-blockers, no cookie loss
• Refund support via paired /postback/refund endpoint = accurate clawback

Method 2 — JS pixel (no backend code)

Add this to your “Order completed” / “Thank you” page:

<script src="https://pixel.keepface.com/p.js" async></script>
<script>
  window.kfaff = window.kfaff || [];
  window.kfaff.push(['track', {
    order_id: 'ord_12345',                    // your unique order id
    currency: 'USD',
    gross_amount_minor: 2500,
    skus: ['list_outreach'],
    customer_email: '[email protected]',      // optional but recommended
  }]);
</script>

Add your storefront domain to Integration → Allowed pixel origins so the pixel accepts your POST.

Why this is good enough for most: zero backend changes, works with any e-commerce stack. Why it’s not ideal: ad-blockers and Safari ITP can drop the pixel. Refund tracking requires Method 1 anyway.

Method 3 — Shopify webhook (Shopify only)

1. Shopify Admin → Settings → Notifications → Webhooks.
2. Add webhook for Order payment event.
3. URL: https://api.keepface.ai/api/v2/affiliate/shopify-webhook/{your_brand_id} (copy from Integration tab).
4. Format: JSON.
5. Save. Shopify shows you a webhook signing secret on this screen.
6. Paste that secret into the Shopify webhook secret field in our Integration tab.
7. Save our settings.

Done. Conversions will start flowing.

Critical: Shopify orders carry the affiliate token in the customer’s cookie at checkout, not in webhook headers. So your Shopify checkout must propagate the cookie value — the official Shopify Online Store 2.0 themes do this automatically via attributes. Custom themes may need a 5-line script. See Shopify integration notes for the snippet.

Discount-code attribution (bonus, all methods)

If a buyer uses an influencer’s discount code but didn’t click the link (saw the code on Instagram, typed it in manually), you can still attribute by including discount_code in your postback body:

{
  "discount_code": "JANE-XYZ123",
  ...rest of payload
}

The backend resolves the code to the affiliate, even if no cookie was set. See Discount-code attribution for the full flow.

---

Stage 5 — Conversion lifecycle

What happens after a successful postback / pixel / webhook.

Postback received
       ↓
[Status: pending]   ← Holdback period starts (default 14 days)
       ↓ (after holdback days, OR you click "Approve" manually)
[Status: approved]
       ↓
Wallet ledger entry:
  - Influencer gets net commission (80% of commission_amount)
  - Keepface system bucket gets 20% (platform fee)
  - Your wallet sees a cost-center book-keeping entry (no real debit; for accounting)
       ↓
[Status: paid]   ← when influencer withdraws or 30 days pass

Refund flow

When a customer refunds on your side, POST to /api/v2/affiliate/postback/refund with the original order_id. We:

1. Mark the conversion refunded
2. Reverse the influencer’s commission (clawback from their wallet)
3. If their wallet is empty, queue the clawback in affiliate_clawback_failures and retry daily

If the conversion was already in approved status, the clawback hits the influencer’s available balance. If they don’t have it, the failure queue catches it and we email them.

Dispute flow

You can manually mark a conversion as disputed if you suspect fraud after approval:

/company/affiliate/conversions → find the row → click Dispute.

The Dispute action on a conversion row in /company/affiliate/conversions.

The conversion enters disputed status. The influencer’s wallet has a hold placed on the disputed amount (they can’t withdraw it while disputed). The influencer gets EN/AZ/TR/RU/AR notifications (email + WhatsApp + Telegram + in-app) and has 5 days to respond. If they don’t respond within 7 days, the dispute auto-resolves in your favor.

Our staff reviews disputed conversions and makes the final call. You can supply evidence (chargeback document, order screenshot) by replying to the dispute thread.

---

Stage 6 — Where to monitor (dashboards)

Your views (brand admin)

URL	What you see
/company/affiliate/settings	Per-brand setup snapshot table. Click Edit to reopen the 6-tab modal.
/company/affiliate/conversions	Every conversion for your brand, with status + filters. Dispute / refund buttons live here.
/company/affiliate/members	Your affiliate roster. Stats per creator: clicks, conversions, earnings. Invite + remove buttons.
/company/affiliate/page	The public landing page editor.

The brand conversions table — status badges, commission column, refund + dispute action buttons.

Your affiliate’s views (read-only for you, FYI)

URL	What they see
/influencer/affiliate	All brand programs they’re in, ranked by earnings.
/influencer/affiliate#my-links	Their link tokens with copy buttons.
/influencer/affiliate/conversions	Per-conversion view with status.
/influencer/affiliate/invitations	Pending invites from brands.

Health metrics to watch the first week

Open the conversions tab and watch these four numbers:

Number	Healthy	Yellow flag	Red flag
Conversions / 24h	growing	flat	dropping after a peak
Open disputes	0	1–3	5+
Postback 401 errors	0	<1% of postbacks	>5% (HMAC misconfigured)
Avg commission per sale	matches your expected % × AOV	drifting	wildly different (SKU mapping wrong)

---

Troubleshooting

Problem	Likely cause	Fix
Postback returns 401 invalid_signature	HMAC secret wrong, or you signed body only (no timestamp)	Sign <timestamp>.<raw_body> not just <raw_body>. Use the rotate button to mint a fresh secret.
Postback returns 401 stale_timestamp	Your server clock is off, or you sent a timestamp from minutes ago	Make sure your X-KF-Timestamp is within 5 min of now. Check NTP on your server.
Postback returns 404 unknown_token	The token doesn’t resolve — bad cookie value, or the influencer’s link was deleted	Log the token you received. If the token looks valid (8 mixed-case alphanumeric chars) and you still get 404, email [email protected] with the token + timestamp and we’ll check the audit log.
Conversion shows but commission % is wrong	Per-SKU override not matching	Check the skus[] array you sent matches the Postback SKU shown in Commission tiers tab exactly (case-sensitive).
Conversion comes in marked unmatched_sku_override	You have per-SKU rates configured + the order’s SKU doesn’t match any of them	Either add the missing SKU in Commission tiers tab, or stop sending unknown SKUs from your postback.
Influencer sees clicks but no conversions	Cookie missing at purchase time	If your checkout is on a different domain than where the click landed (subdomain cross-site), the cookie isn’t traveling. Use server-side postback or set up the tracking subdomain CNAME.
Refund didn’t claw back	Refund postback never reached us, or the order_id didn’t match	Re-send your refund postback (it’s idempotent). If still no effect after 1 hour, email [email protected] with the order_id and we’ll check delivery on our side.

---

What to read next

• Quick-start (10 minutes) — the express version of this guide
• Postback HMAC integration — full Node/PHP/Python recipes + Shopify edge cases
• Discount-code attribution — capture sales when buyers paste a code instead of clicking
• API reference — full HTTP contract, error codes, rate limits