3-Step Integration Guide

Three steps get Affitor tracking live: clicks → signups → sales. Steps 1 and 2 establish attribution; step 3 records revenue.

Follow https://affitor.com/docs/skill.md to integrate Affitor. Program <PROGRAM_ID> on https://api.affitor.com. Key in AFFITOR_API_KEY.

Before You StartCopy Anchor Link

Make sure you have:

• Your program ID
• Your program API key for server-to-server calls
• A decision on how you will track sales (server-side tracking vs Stripe integration):
  • Server-side tracking — your backend calls POST /api/v1/track/sale — for any backend or payment provider
  • Stripe integration — attach Affitor metadata to Stripe Checkout sessions

Step 1 — Install the TrackerCopy Anchor Link

Add the tracker to every page where affiliate traffic can land.

<script
  src="https://api.affitor.com/js/affitor-tracker.js"
  data-affitor-program-id="YOUR_PROGRAM_ID"
  data-affitor-debug="false">
</script>

Replace YOUR_PROGRAM_ID with your program ID (program menu → Program settings → Business → Program ID, Copy).

What this doesCopy Anchor Link

• Detects affiliate visits via the ?aff= parameter
• Creates a tracked customer / click relationship
• Stores affitor_click_id in a first-party cookie
• Sends click/pageview tracking data to Affitor

VerifyCopy Anchor Link

Visit your site through a real affiliate link or enable debug mode while testing. Then review:

• browser console / network requests
• Affitor dashboard → tracking/integration pages

Step 2 — Track SignupsCopy Anchor Link

After signup succeeds, tell Affitor which internal user was created.

Option A — Browser-side helperCopy Anchor Link

Use this when your signup flow runs in the browser and the tracker is already loaded.

<script>
await window.affitor.signup('user_123', 'user@example.com');
</script>

Or inside your signup flow:

<script>
document.getElementById('signup-form').addEventListener('submit', async function(e) {
  e.preventDefault();

  const email = document.getElementById('email').value;

  // Run your own signup logic first.
  // After account creation succeeds:
  await window.affitor.signup(currentUser.id, email);
});
</script>

Use this when:

• you already installed the tracker on the page
• signup happens in the browser
• you want the simplest supported flow

By default a browser-only lead is provisional: it does not count as a signup until your server sends the lead (Option B) or a Stripe Checkout payment for that customer arrives through your connected Stripe account. See lead auth policy.

Option B — Server-side lead APICopy Anchor Link

Use this when signup logic lives on your backend or you want the server to own the tracking call.

POST https://api.affitor.com/api/v1/track/lead
Authorization: Bearer YOUR_PROGRAM_API_KEY
Content-Type: application/json

{
  "click_id": "cust_42_1234567890",
  "customer_key": "user_123",
  "email": "user@example.com"
}

await fetch('https://api.affitor.com/api/v1/track/lead', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.AFFITOR_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    click_id: req.cookies.affitor_click_id,
    customer_key: newUser.id,
    email: newUser.email,
  }),
});

Lead tracking rulesCopy Anchor Link

• Outside test mode, send the click_id from the affitor_click_id cookie: Affitor finds the customer through it. From your server, a first lead with only customer_key answers 400 Customer not found. Provide a valid click_id or customer_key.; from the browser, click_id is always required.
• For reliable payment attribution later, always send a stable internal customer ID:
  • customerKey in signup()
  • customer_key in the API
• Browser-side signup() is the easiest to add, but by default it stays provisional until the server-side lead or a Stripe Checkout payment through your connected Stripe account
• Server-side API is best when signup completes on your backend

Response:

{
  "success": true,
  "message": "Lead tracked successfully"
}

Step 3 — Track SalesCopy Anchor Link

When a customer pays, choose one revenue-tracking path.

Option A — Server-side tracking (works with any payment provider)Copy Anchor Link

Send a server-to-server request once payment succeeds.

Endpoint: POST https://api.affitor.com/api/v1/track/sale

{
  "transaction_id": "txn_abc123",
  "customer_key": "user_123",
  "click_id": "cust_42_123456",
  "amount_cents": 9999,
  "currency": "USD",
  "sale_type": "payment",
  "is_recurring": false,
  "subscription_id": "sub_xyz",
  "subscription_interval": "monthly",
  "product_id": "prod_456",
  "line_items": [
    { "name": "Pro Plan", "amount_cents": 9999, "quantity": 1 }
  ]
}

await fetch('https://api.affitor.com/api/v1/track/sale', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.AFFITOR_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    transaction_id: order.id,
    customer_key: currentUser.id,
    click_id: req.cookies.affitor_click_id,
    amount_cents: order.totalCents,
    currency: 'USD',
    sale_type: 'payment',
  }),
});

Response:

{
  "success": true,
  "sale_id": 42,
  "commission_id": 18,
  "message": "Sale tracked successfully"
}

Option B — Stripe integrationCopy Anchor Link

If you already use Stripe Checkout, keep taking payment in your own Stripe account. Connect it under Program settings › Payments (Affitor receives its events through Stripe Connect, with no webhook to add), then attach Affitor metadata to the checkout session.

const session = await stripe.checkout.sessions.create({
  line_items: [{ price: 'price_xxx', quantity: 1 }],
  mode: 'payment',
  success_url: 'https://yoursite.com/success',
  cancel_url: 'https://yoursite.com/cancel',
  metadata: {
    affitor_click_id: clickId,
    affitor_customer_key: currentUser.id,
    program_id: 'YOUR_PROGRAM_ID',
  },
});

For subscriptionsCopy Anchor Link

Put the same fields in subscription_data.metadata: a subscription's payments are read from its invoices, which carry the subscription's metadata, not the session's. Setting them in metadata too does no harm.

const session = await stripe.checkout.sessions.create({
  line_items: [{ price: 'price_xxx', quantity: 1 }],
  mode: 'subscription',
  success_url: 'https://yoursite.com/success',
  cancel_url: 'https://yoursite.com/cancel',
  metadata: {
    affitor_click_id: clickId,
    affitor_customer_key: currentUser.id,
    program_id: 'YOUR_PROGRAM_ID',
  },
  subscription_data: {
    metadata: {
      affitor_click_id: clickId,
      affitor_customer_key: currentUser.id,
      program_id: 'YOUR_PROGRAM_ID',
    },
  },
});

Stripe integration rulesCopy Anchor Link

• One-time payments are attributed from Stripe checkout metadata and webhook processing
• Subscriptions and renewals rely on invoice.payment_succeeded
• If subscription_data.metadata is missing, the click does not reach the subscription's invoices (first payment and renewals), and Affitor attributes the subscription only by the buyer's email or Stripe customer ID
• Metadata fields to set on every checkout (recommended; none is strictly required):
  • affitor_click_id
  • affitor_customer_key
  • program_id

Which Sales Path Should You Use?Copy Anchor Link

Use server-side tracking when your backend controls the revenue event. Use Stripe integration when you want Affitor to attribute sales directly from the payment events of your connected Stripe account.

Verify it workedCopy Anchor Link

You're DoneCopy Anchor Link

All three steps working means your integration is live:

Next:

• Testing Integration
• Payment Tracking
• Payment Flow