Documentation

MassPartner documentation

Step-by-step guides for brands running an affiliate program on MassPartner and for affiliates promoting one. Exact parameters, responses and error messages are in the API reference.

Last updated 12 October 2026

Contents
  1. Start here
  2. Getting started
  3. Account and sign-in
  4. Programs
  5. Campaigns and programs
  6. Approving affiliates
  7. Tracking
  8. How tracking works
  9. Tracking links and sub IDs
  10. Banners and creatives
  11. Install the tracking script
  12. Send postbacks
  13. Secure your postbacks
  14. Test your setup
  15. Conversions and money
  16. Approve conversions
  17. Fraud and country rules
  18. Payments and payouts
  19. Affiliate tools
  20. Callbacks to your tracker
  21. Google Ads and Microsoft Ads
  22. Help
  23. Troubleshooting
  24. API reference

Getting started

MassPartner connects brands, who run an affiliate program, with affiliates, who promote it. A brand publishes campaigns, affiliates join them and share tracking links, and every conversion is attributed, approved and paid according to the campaign's rules.

For brands

Run your own affiliate program.

  1. Create a brand account (7-day free trial).
  2. Create a campaign with your commission.
  3. Upload banners that point to your site.
  4. Install the tracking script.
  5. Send postbacks from your server and secure them.
  6. Approve affiliates and review conversions.
  7. Pay your affiliates.

For affiliates

Free to join; no fee is taken from your commissions.

  1. Create an affiliate account.
  2. Add your payout details.
  3. Join programs in the marketplace.
  4. Get your tracking links and add sub IDs.
  5. Optional: send conversions to your tracker and upload them to Google Ads or Microsoft Ads.
  6. Follow conversions, commissions and payouts in your dashboard.

Account and sign-in

Create an account

  • Brands sign up at /register?type=brand. Every plan starts with a 7-day free trial; choose or change your plan on the Subscription page of the dashboard. Plans and limits are on the pricing page.
  • Affiliates sign up for free at /register?type=affiliate.
  • Confirm your email address with the link we send after registration.

Sign in and passwords

  • Sign in at /login. You land on the brand or affiliate dashboard that belongs to your account.
  • Forgot your password? Request a reset link at /password-reset.
  • To change your password while signed in, use Change Password on the Profile page (affiliates) or the Settings page (brands). New passwords need at least 8 characters.

Profile and settings

  • Affiliates: the Profile page holds your public details and your payout method (PayPal, Payoneer, bank transfer or crypto) with the matching payment details. Brands use these details when they pay you.
  • Brands: the Settings page holds your company details, contact email and the Auto-Approve Affiliates option described in approving affiliates.

Close your account

Email [email protected] from the address on your account with the subject "Account Closure Request".

Campaigns and programs

A campaign defines what a brand pays for, how much, where and under which approval rules. A brand's program is the set of its campaigns.

For affiliates: find and join programs

  1. Browse the marketplace or the affiliate program directory and open a brand to see its campaigns, commission model, rate and country rules.
  2. Apply to the brand. If the brand uses a contract, read and sign it as part of the application.
  3. Depending on the brand's settings you are approved immediately or after the brand reviews your application. You receive an email when the status changes.
  4. Approved brands are listed on My Brands; their campaigns are on Campaigns. Signed agreements are on Contracts.

Clicks are only counted while you are approved for the brand. Links shared before approval, or after a brand suspends the partnership, do not record clicks.

For brands: create a campaign

Open Campaigns in the brand dashboard and create a new campaign. The settings that affect tracking and payouts:

SettingWhat it does
Landing Page URLWhere the campaign sends visitors. Your banners and links point to your own site.
Commission Type and AmountCPA, CPS, CPL, CPC, CPI, RevShare or Hybrid. Fixed types use the amount; CPS and RevShare use it as a percentage of the sale amount you report. See which events pay for each type.
Minimum Sale AmountCPA only: sales below this amount earn no commission.
Payout ModelFirst purchase only, All purchases, Recurring payments (with recurring percentage and duration) or Lifetime value (with an optional RevShare duration).
Allowed and Blocked CountriesClicks from other countries are stored as blocked and cannot convert. See country rules.
Conversion CapsDaily, monthly and total caps. Conversions above a cap are recorded with zero commission.
Approval SettingsSeparate modes for purchases and for registrations: auto-approve, manual review, or delayed approval after a number of days. See approving conversions.
Status and scheduleOnly active campaigns inside their start and end dates accept conversions.
Private and featuredPrivate campaigns are hidden from the marketplace and offered only to affiliates you grant access; featured campaigns are highlighted.

Approving affiliates

  • Applications appear on the Affiliates page of the brand dashboard. Approve or reject them, and suspend a partnership later if needed.
  • With Auto-Approve Affiliates enabled in Settings, affiliates who sign your contract are approved immediately.
  • Use Contracts to publish the agreement affiliates sign when they apply. Payment terms such as the payout schedule and minimum payout belong in that contract.
  • Only approved affiliates generate clicks and conversions.

How tracking works

MassPartner uses first-party tracking on the brand's own domain plus a server-to-server postback. Nothing depends on third-party cookies.

  1. The affiliate shares a tracking link that points straight to the brand's site and contains aff_id, the campaign and optional sub IDs.
  2. The visitor lands on the brand's site. The tracking script sees aff_id, records the click and stores its click ID in the mp_click cookie for the campaign's cookie duration (set per campaign, for example 90 days). A newer affiliate click replaces it, so the last click wins. Safari keeps cookies set by JavaScript for at most 7 days between visits, so also save the click ID on your server at sign-up.
  3. When the visitor registers or pays, the brand's server reads the click ID and sends a postback.
  4. MassPartner finds the click, the affiliate and the campaign, calculates the commission and applies the approval rules.
  5. The affiliate sees the conversion in the dashboard, and their callbacks fire.
  6. Approved commissions are paid out by the brand through payout batches.

Clicks, conversions and commissions are visible on the Reports, Conversions and Commissions pages of both dashboards. Every conversion keeps the sub IDs of its click, so affiliates can break results down by their own sources.

Banners and creatives

For brands: upload creatives

Add image, HTML5, video and text-link creatives on the Banners page. Each creative has a destination URL on your own website and can be tied to a campaign. Affiliates only see creatives of brands they are approved for.

For affiliates: embed a creative

In Banners & Links, Get Code offers four output types. Every one of them carries your tracking link with the campaign, banner and sub IDs you entered.

Output typeWhat you get
Direct linkThe tracking URL only, for buttons, posts, emails or your own tracker.
HTMLReady-made markup: a linked image, a text link, a video or the HTML5 banner.
IframeAn <iframe> embed with the banner's width and height.
ScriptA <script> tag that writes the iframe into the page.

Install the tracking script

Brands: copy the snippet from the Tracking page of your dashboard and paste it before the closing </head> tag of every page that receives affiliate traffic. In a layout or template file (for example layout.php, _app.tsx, theme.liquid or a WordPress wp_head hook) one insertion covers the whole site. The snippet in your dashboard already contains your brand ID:

HTML
<!-- MassPartner Tracking Code -->
<script>
(function() {
    // Check if aff_id parameter exists in URL
    const urlParams = new URLSearchParams(window.location.search);
    const affId = urlParams.get('aff_id');

    // Only load and initialize tracker if aff_id is present
    if (affId) {
        var script = document.createElement('script');
        script.src = 'https://masspartner.com/public/js/tracker.js';
        script.async = true;
        script.onload = function() {
            if (typeof MassPartner !== 'undefined') {
                MassPartner.init({
                    brandId: 'YOUR_BRAND_ID',
                    apiEndpoint: 'https://masspartner.com/api/tracking',
                    cookieDuration: 30,
                    collectFingerprint: true,
                    fingerprintDelay: 3000
                });
            }
        };
        document.head.appendChild(script);
    }
})();
</script>
  • It does nothing on visits without aff_id, so regular traffic is not affected.
  • On affiliate visits it records the click and sets the first-party mp_click cookie for the campaign's cookie duration on the host the visitor landed on. If registration or checkout happens on another subdomain, save the click ID on the customer record at sign-up (see postbacks).
  • It sends a device fingerprint a few seconds after the visit for fraud scoring. Mention the cookie and fingerprinting in your privacy or cookie policy where required, and make sure your consent tool does not block the script on affiliate landings if you rely on it.
  • The Test Installation button on the Tracking page checks that the snippet is present on your website.

The cookie format is documented in the API reference.

Send conversions with postbacks

A postback is an HTTP request from your server to MassPartner that reports a conversion. Send it from your back end, never from the browser, and only for visitors who have a click ID.

1. Read the click ID

PHP

PHP
<?php
// The tracking script stores the click in the mp_click cookie on your domain.
// PHP has already URL-decoded the cookie value; it contains JSON.
function masspartner_click_id(): ?string
{
    if (empty($_COOKIE['mp_click'])) {
        return null; // visitor did not arrive through an affiliate link
    }
    $data = json_decode($_COOKIE['mp_click'], true);
    $clickId = is_array($data) ? ($data['click_id'] ?? null) : null;

    return (is_string($clickId) && preg_match('/^[a-f0-9-]{32,36}$/i', $clickId)) ? $clickId : null;
}

Node.js

JavaScript
// Express with cookie-parser: req.cookies values are already URL-decoded
function masspartnerClickId(req) {
  const raw = req.cookies && req.cookies.mp_click;
  if (!raw) return null; // visitor did not arrive through an affiliate link
  try {
    const clickId = JSON.parse(raw).click_id;
    return /^[a-f0-9-]{32,36}$/i.test(clickId) ? clickId : null;
  } catch (e) {
    return null;
  }
}

2. Store it on the customer

Save the click ID on the user record when the account is created. Payment webhooks (Stripe, PayPal and similar) do not carry the visitor's cookies, and checkout may happen days later or on another device.

SQL
ALTER TABLE users ADD COLUMN mp_click_id VARCHAR(32) NULL;

3. Send the postback

Send event=registration when an account is created and event=sale (or deposit) when a payment is confirmed. Include amount for percentage commissions and user_id so returning customers are recognised. Your postback URL and secret are on the Tracking page.

PHP

PHP
<?php
// Server-side postback with the token credential (form-encoded POST).
function masspartner_postback(array $params): void
{
    $params['token'] = getenv('MASSPARTNER_POSTBACK_SECRET');

    $ch = curl_init('https://masspartner.com/api/postback/' . getenv('MASSPARTNER_BRAND_ID'));
    curl_setopt_array($ch, [
        CURLOPT_POST           => true,
        CURLOPT_POSTFIELDS     => http_build_query($params),
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_CONNECTTIMEOUT => 5,
        CURLOPT_TIMEOUT        => 5,
    ]);
    $body   = curl_exec($ch);
    $status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    if ($status !== 200) {
        error_log('MassPartner postback HTTP ' . $status . ': ' . $body);
    }
}

// 1. After the user account has been created
$clickId = masspartner_click_id();
if ($clickId !== null) {
    $db->prepare('UPDATE users SET mp_click_id = ? WHERE id = ?')->execute([$clickId, $userId]);
    masspartner_postback(['click_id' => $clickId, 'event' => 'registration', 'user_id' => (string) $userId]);
}

// 2. After a payment is confirmed (for example in your payment provider's webhook)
if (!empty($user['mp_click_id'])) {
    masspartner_postback([
        'click_id' => $user['mp_click_id'],
        'event'    => 'sale',
        'amount'   => number_format($order['total'], 2, '.', ''),
        'currency' => $order['currency'],
        'order_id' => (string) $order['id'],
        'user_id'  => (string) $user['id'],
    ]);
}

Node.js

JavaScript
// Node.js 18+ (built-in fetch). Server-side postback with the token credential.
const BRAND_ID = process.env.MASSPARTNER_BRAND_ID;
const SECRET = process.env.MASSPARTNER_POSTBACK_SECRET;

async function masspartnerPostback(params) {
  try {
    const res = await fetch(`https://masspartner.com/api/postback/${BRAND_ID}`, {
      method: 'POST',
      body: new URLSearchParams({ ...params, token: SECRET }), // form-encoded
      signal: AbortSignal.timeout(5000),
    });
    const data = await res.json();
    if (!data.success) console.error('MassPartner postback:', res.status, data.message);
  } catch (err) {
    console.error('MassPartner postback failed:', err.message); // never block your own flow
  }
}

// 1. After sign-up
const clickId = masspartnerClickId(req);
if (clickId) {
  await db.users.update(user.id, { mp_click_id: clickId });
  masspartnerPostback({ click_id: clickId, event: 'registration', user_id: String(user.id) });
}

// 2. After a confirmed payment
if (user.mp_click_id) {
  masspartnerPostback({
    click_id: user.mp_click_id,
    event: 'sale',
    amount: order.total.toFixed(2),
    currency: order.currency,
    order_id: String(order.id),
    user_id: String(user.id),
  });
}

Rules of thumb

  • No click ID means no affiliate visit: skip the postback.
  • Do not send campaign_id; the campaign comes from the click.
  • Send each order once. order_id is stored and shown to the affiliate but not de-duplicated. Repeated registrations for the same click are ignored automatically.
  • Fire the sale postback when the payment is confirmed (for example in the payment webhook), not on the thank-you page, which can be reloaded.
  • Treat the postback as fire-and-forget with a short timeout so a network problem never blocks your sign-up or checkout.
  • On CPA campaigns a registration earns nothing; the sale does. On CPL campaigns the registration or lead pays once per click. Details: commission rules.

Every parameter, event value, response and error message is listed in the API reference.

Secure your postbacks

Anyone who knows a click ID could otherwise report a fake conversion, so every postback should carry your postback secret.

  1. Open the Tracking page and scroll to Postback authentication. There you find your postback secret (hidden until you click Reveal), the Full URL template with your token already filled in, Regenerate secret and the mode setting.
  2. Add the secret to every postback, either as the token parameter (as in the examples above) or as an X-MP-Signature HMAC header. Keep it in an environment variable on your server, never in browser code, apps or a public repository.
  3. While the mode is Grace (the default), postbacks without a valid secret are still recorded, but their conversions are never approved automatically and are flagged as unauthenticated for your review. The response tells you with "authenticated": false, and the Tracking page counts unauthenticated postbacks of the last 30 days.
  4. When that count stays at zero, switch to Strict. From then on, postbacks without a valid secret are rejected with HTTP 401 and nothing is recorded.

If the secret leaks, regenerate it and deploy the new value; the old secret stops working immediately, so switch to Grace during the change to avoid losing conversions. Copy-ready token and HMAC examples for curl, PHP and Node.js are in the API reference.

Test your setup

  1. Create a separate affiliate account with another email address, apply to your own program and approve it. Clicks are only recorded for real, approved affiliates, so placeholder affiliate IDs never produce a cookie.
  2. Signed in as that affiliate, copy a Direct link from Banners & Links.
  3. Open the link in a private browser window. In the developer tools (Application, Cookies) you should see mp_click on your domain.
  4. Register or buy as a test customer, or send a postback by hand with the click ID from the cookie:
Shell
curl -sS -X POST "https://masspartner.com/api/postback/YOUR_BRAND_ID" \
  --data-urlencode "token=YOUR_POSTBACK_SECRET" \
  --data-urlencode "click_id=CLICK_ID_FROM_YOUR_TEST_COOKIE" \
  --data-urlencode "event=sale" \
  --data-urlencode "amount=10.00" \
  --data-urlencode "order_id=TEST-1"

A response with "success": true and a conversion_id means the conversion was recorded. It appears on the Conversions page; reject test conversions afterwards so they are never paid.

Approve conversions

Every conversion has a status: pending, approved or rejected. Only approved conversions with a commission above zero create a payable commission.

Approval modes

Each campaign has one mode for registrations and one for purchases and all other events:

  • Auto-approve: conversions are approved immediately, unless the click has a very high fraud score (90 or more) or the postback was unauthenticated in Grace mode. Those stay pending for you.
  • Manual review: every conversion waits for your decision.
  • Delayed approval: conversions are approved automatically after the number of days you set, which leaves time for refunds and chargebacks. Reject a conversion before the delay ends to stop it.

Review on the Conversions page

  • Filter by status, approve or reject single conversions, or select several and use Approve selected or Reject selected.
  • Give a reason when you reject; the affiliate sees the status change in their dashboard.
  • Export the filtered list as CSV for reconciliation with your own orders.

Affiliates follow the same statuses on their Conversions and Commissions pages and can receive them in their tracker through callbacks.

Fraud and country rules

  • Fraud score. Every click is scored from 0 to 100 using bot and user-agent signals, data-center, proxy and VPN addresses, click velocity from the same IP and IP reputation. Scores from 30 count as suspicious and from 70 as likely fraud. Conversions from clicks with a score of 90 or more are never approved automatically.
  • Country rules. Set allowed or blocked countries on the campaign. A click from a country outside the allowed list, or on the blocked list, is stored as blocked with the reason "Country prohibited", no cookie is set, and the visit cannot convert. The visitor still sees your page.
  • Unauthenticated postbacks. In Grace mode they are flagged and held for review; in Strict mode they are rejected. See securing postbacks.
  • Manual control. Manual or delayed approval gives you time to check orders before commissions become payable, and you can suspend an affiliate on the Affiliates page at any time.

Payments and payouts

Brands pay their affiliates directly. MassPartner calculates what is owed, groups it into payout batches and produces the payment files; it does not hold or transfer the money.

For brands: pay your affiliates

  1. Open Payouts and select the Create payout tab.
  2. Choose the period and click Load affiliates with balance. The list shows each affiliate's approved commissions that are not yet in a payout.
  3. Select the affiliates and click Create payout batch. Each affiliate receives an email about the payout.
  4. Export the batch as CSV or as a PayPal mass payment file and send the money through your payment provider using each affiliate's payout method.

Your payout schedule and minimum payout are part of your affiliate contract, so state them there.

For affiliates: get paid

  • Set your payout method (PayPal, Payoneer, bank transfer or crypto) and its details on the Profile page. Keep them current; brands pay to the details stored there.
  • Commissions shows each commission and its status; Payouts lists the payouts brands have created for you.
  • Each brand sets its own payout schedule and minimum in its contract, which you find on the Contracts page.
  • MassPartner does not take a fee from affiliate commissions.

Callbacks to your tracker

Affiliates can forward conversions to their own tracker or server as they happen.

  1. Put your tracker's click ID into a sub ID of your MassPartner link, for example &sub1={clickid} using your tracker's own macro.
  2. Open Callbacks in the affiliate dashboard and click Add callback.
  3. Enter a name and your tracker's postback URL with MassPartner placeholders, choose GET, and tick the events you want: conversion created, approved or rejected, sale, first sale, recurring sale, or refund.
  4. Save, then click Send test to check that your tracker receives the call.

From then on, each matching event triggers one request with the placeholders replaced by URL-encoded values. Calls time out after 5 seconds. Failed calls (timeouts, network errors, 5xx, 408 and 429) are retried after 5 minutes, 30 minutes and 2 hours; other 4xx responses are not retried. The Callbacks page shows the number of calls, failures and the last error of each callback.

Callback URL
https://tracker.example.com/postback?subid={$sub1}&payout={$commission}&currency={$currency}&status={$status}&txid={$orderid}

MassPartner placeholders have a dollar sign, such as {$sub1}, {$commission} or {$status}, so they do not collide with your tracker's macros. Choose POST instead to receive a JSON body. All placeholders, the POST body and the delivery rules are in the API reference.

Google Ads and Microsoft Ads

If you buy ads on Google Ads or Microsoft Ads, you can send approved conversions back to the ad platform as an offline conversion import.

  1. Capture the ad click ID in a sub ID. Add sub1={gclid} (Google Ads) or sub1={msclkid} (Microsoft Ads) to the tracking template or final URL suffix of your ads. If your ads lead to your own pre-landing page, pass the click ID into sub1 of the MassPartner link on that page.
  2. Create an offline conversion action. In Google Ads, create a conversion action whose source is "Import from clicks"; in Microsoft Ads, an offline conversion goal. Wait a few hours before the first upload.
  3. Export. On the Exports page choose the platform, the conversion status (Approved only is recommended), the date range (up to 90 days back, in UTC), the sub ID that holds the click ID, the conversion action name and whether the value is your commission or the sale amount. The action name must match the one in your ad account exactly. Then download the CSV.
  4. Upload the file: in Google Ads under Goals, Conversions, Uploads; in Microsoft Ads under Conversions, Offline conversions.

Rows without a valid click ID are skipped, and rejected or refunded conversions are never exported. The file format is described in the API reference.

Troubleshooting

No mp_click cookie after clicking a link

  • The snippet is missing on the landing page, or a consent tool or ad blocker stops it from loading.
  • The link has no aff_id, or the affiliate is not approved for the brand (or is a placeholder ID).
  • The visitor's country is blocked for the campaign.
  • You are looking at a different subdomain than the one the visitor landed on.

The postback returns "Click not found"

  • The brand ID in the postback URL is wrong, or the click belongs to another brand.
  • The click ID was read from the wrong cookie or truncated. It must be the 32-character value from mp_click.

The conversion was recorded but earned nothing

  • The event does not pay for the campaign's commission type, for example a registration on a CPA campaign.
  • The payout model already paid for this click or customer (First purchase only), a conversion cap was reached, or the sale is below the minimum sale amount.
  • For percentage commissions, amount was missing.

The conversion stays pending

  • The campaign uses manual or delayed approval.
  • The click's fraud score is 90 or higher.
  • The postback was sent without a valid secret while in Grace mode (the response shows "authenticated": false).

The postback returns 401

  • Strict mode is on and the token is missing, mistyped or outdated after a secret regeneration.
  • With signatures: the canonical query differs from what you sent, or your server clock is more than 300 seconds off.

Still stuck? Visit the support center or contact us with the conversion or click ID.