Tracking and postback API reference
Exact parameters, responses and error messages for MassPartner tracking links, the tracking script, server-to-server postbacks and affiliate callbacks. Step-by-step setup lives in the documentation.
On this page
- Overview
- Integration surface
- Conventions
- Brand integration
- Tracking link parameters
- Tracking script and cookie
- Postback endpoint
- Postback parameters
- Event values
- Commission rules
- Responses
- Errors
- Authentication
- Modes and credentials
- Token
- HMAC signature
- Signature test vector
- Affiliate integration
- Callbacks
- Callback placeholders
- Ad platform exports
- More
- What is not available
Integration surface
MassPartner exposes a small integration surface. Brands connect their website and back end; affiliates connect their own tracker and ad accounts. Everything below is available on every plan.
| Surface | Used by | Direction | Reference |
|---|---|---|---|
| Tracking link | Affiliates | Visitor to the brand's website | Parameters |
| Tracking script | Brands | Brand website to MassPartner | Script and cookie |
| Postback endpoint | Brands | Brand server to MassPartner | Endpoint |
| Callbacks | Affiliates | MassPartner to the affiliate's tracker | Callbacks |
| Export files | Affiliates | CSV for Google Ads and Microsoft Ads | Exports |
The flow is always the same: an affiliate's link brings a visitor to the brand's site, the tracking script records the click and stores a click ID in a first-party cookie, and the brand's server reports the conversion with that click ID through a postback. MassPartner calculates the commission, applies the campaign's approval rules and notifies the affiliate's tracker through callbacks.
Conventions
- Host. All endpoints are served from
https://masspartner.comover HTTPS. - Identifiers. Brand, affiliate, campaign, banner and conversion IDs are UUIDs, for example
6f1c2d3e-4b5a-4c6d-8e7f-9a0b1c2d3e4f. Click IDs are 128-bit identifiers; the tracking cookie holds them as 32 hexadecimal characters, for example3f2b8c1d9e4a5b6c7d8e9f0a1b2c3d4e. Send the value from the cookie unchanged. - Your brand ID is part of the postback URL shown on the Tracking page of the brand dashboard.
- Responses are JSON encoded as UTF-8. Amounts use a dot as the decimal separator (
49.99). - Server to server only. Postbacks must be sent from your server. Never put your postback secret in browser code.
Tracking link parameters
An affiliate tracking link points directly at the brand's own landing page (the destination URL of the campaign's creative) and carries the parameters below. There is no MassPartner redirect in between: the brand's tracking script records the click when the page loads.
https://www.brand-site.example/landing?aff_id=6f1c2d3e-4b5a-4c6d-8e7f-9a0b1c2d3e4f&campaign_id=0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d&banner_id=5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b&sub1=fb_campaign_12&sub2=adset_7| Parameter | Required | Format | Description |
|---|---|---|---|
aff_id | Yes | UUID | The affiliate's ID. The tracking script does nothing when this parameter is missing. |
campaign_id | Recommended | UUID | The campaign the click belongs to. cid is accepted as an alias, and the script also reads a data-mp-campaign-id attribute on the page. Without a campaign, conversions are attributed to the brand's first active campaign. |
banner_id | No | UUID | The creative that was used, for per-banner reporting. Invalid values are ignored. |
sub1 to sub5 | No | Text, up to 255 characters | The affiliate's own tracking values (traffic source, ad ID, the click ID of their tracker). Longer values are truncated. They are copied onto every conversion from the click and returned in callbacks and exports. |
When a click is recorded
- The affiliate must exist and be approved for the brand. For unknown, pending or suspended affiliates the click endpoint answers with success but returns no click ID, so no cookie is set and no conversion can be attributed.
- If the campaign has allowed countries and the visitor's country is not on the list, or the country is on the blocked countries list, the click is stored as blocked with the reason
Country prohibitedand no click ID is returned. - Every visit with an
aff_idcreates a new click with a new click ID and overwrites the cookie, so the last affiliate click wins. - Each click receives a fraud score from 0 to 100 (bot and user-agent signals, data-center, proxy and VPN addresses, click velocity, IP reputation). The score decides whether conversions can be approved automatically; see commission rules.
Tracking script and cookie
Brands install the snippet from the Tracking page in the <head> of every page that can receive affiliate traffic. The snippet in your dashboard already contains your brand ID; it looks like this:
<!-- 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>What it does, in order:
- Exits immediately unless the page URL contains
aff_id, so regular traffic is not affected. - Loads
/public/js/tracker.jsand sends the click (brand ID, affiliate ID, campaign ID, banner ID,sub1tosub5, page URL, referrer, user agent, screen size, time zone and language) toPOST /api/tracking/click.php. You never need to call this endpoint yourself. - Stores the returned click ID in the
mp_clickcookie. - About three seconds later sends a device fingerprint (canvas, WebGL, audio, fonts and plugins) used only for fraud scoring. Mention this in your privacy or cookie policy where required.
The mp_click cookie
| Property | Value |
|---|---|
| Name | mp_click |
| Scope | First-party, set by JavaScript on the exact host that served the landing page, path=/. It is not shared with other subdomains. |
| Lifetime | The campaign's cookie duration (set per campaign) from the last affiliate click. Safari caps cookies set by JavaScript at 7 days; the tracker refreshes the cookie on each visit within the campaign window. |
| SameSite | Lax |
| Value | URL-encoded JSON. Only click_id is needed for postbacks. |
mp_click=%7B%22click_id%22%3A%223f2b8c1d9e4a5b6c7d8e9f0a1b2c3d4e%22%2C...%7D
// decoded value
{
"click_id": "3f2b8c1d9e4a5b6c7d8e9f0a1b2c3d4e",
"affiliate_id": "6f1c2d3e-4b5a-4c6d-8e7f-9a0b1c2d3e4f",
"subParams": {},
"timestamp": 1760000000000
}PHP and most Node.js cookie parsers URL-decode cookie values for you, so you only need to JSON-decode the value and read click_id. The postback guide has copy-ready snippets for reading it on your server.
Postback endpoint
Report a conversion (registration, lead, sale, deposit and so on) from your server.
https://masspartner.com/api/postback/{brand_id}{brand_id}is your brand UUID. Copy the complete URL from the Tracking page.- With GET, send the parameters in the query string.
- With POST, send them as
application/x-www-form-urlencoded(ormultipart/form-data). JSON request bodies are not read. Query and body parameters are merged; if a name appears in both, the body value wins. - Authenticate every request with your postback secret, either as a token parameter or an HMAC signature header.
Postback parameters
| Parameter | Required | Description |
|---|---|---|
click_id | Yes | The click ID from the mp_click cookie, or the one you stored on the customer record. It must belong to a click on your brand. |
event | Yes | What happened. See event values. Case-insensitive. |
amount | For sales | Sale or deposit value, for example 49.99. sale_amount is accepted as an alias. Required for percentage-based commissions (CPS, RevShare) and for the minimum sale amount check. |
currency | No | Three-letter ISO 4217 code of the amount, default USD; other values are stored as USD. Amounts are not converted between currencies. |
order_id | Recommended | Your order or transaction ID. Shown with the conversion and passed to affiliate callbacks. It is not used for de-duplication. |
user_id | Recommended | Your customer ID. Required for the First purchase only payout model to recognise a returning customer who arrives through a new click. |
commission | No | A commission amount you calculated yourself. Replaces the campaign's calculation; caps and payout-model rules still apply. |
product_id | No | Stored with the conversion. |
product_name | No | Stored with the conversion. |
token | See authentication | Your postback secret. Not needed when you sign the request with X-MP-Signature. |
Do not send campaign_id or affiliate_id: MassPartner resolves the campaign, the affiliate and the sub IDs from the click. Other parameters are ignored, and text values longer than 255 characters are truncated.
Event values
Send event= | Recorded as | Notes |
|---|---|---|
registration, signup, register | registration | One per click. Repeats return the existing conversion instead of creating a new one. |
lead, cpl | lead | |
sale, cps | sale | Use for purchases and orders. |
purchase | purchase | |
deposit | deposit | For example a first deposit in iGaming or trading. |
subscription | subscription | |
install, cpi | install | App installs. |
cpa | cpa | Generic qualifying action. |
conversion, action | conversion, action | Generic. |
| anything else | sale | Unknown values are recorded as a sale. |
Commission rules
Every accepted postback creates a conversion. Whether it earns a commission depends on the campaign's commission type and the event.
| Commission type | Events that pay | Commission |
|---|---|---|
| CPA | sale, purchase, deposit, subscription, cpa, conversion, action | Fixed amount. Zero when amount is below the campaign's minimum sale amount. |
| CPS | sale, purchase, deposit, subscription, conversion | Percentage of amount. |
| RevShare | sale, purchase, deposit, subscription, conversion | Percentage of amount. |
| CPL | registration, lead, install, sale | Fixed amount, at most once per click. |
| CPI | install | Fixed amount. |
| CPC | any event | Fixed amount, at most once per click. Paid when a conversion is reported, not for the click alone. |
| Hybrid | sale, purchase, deposit, subscription, cpa, conversion | Fixed amount. |
A registration on a CPA campaign is therefore recorded with a zero commission; send a sale or deposit event when the customer pays.
Payout model
| Payout model | Behaviour |
|---|---|
| First purchase only (default) | Pays once per click and, when you send user_id, once per customer across clicks. Later conversions are recorded with zero commission. |
| All purchases | Every qualifying event pays. |
| Recurring payments | The first paid conversion of a click pays the normal commission. Later ones pay the recurring commission percentage of amount (when set) until the recurring duration in months has passed. |
| Lifetime value | Every qualifying event pays until the RevShare duration in days has passed since the first paid conversion of the click; with no duration it never expires. |
Limits that apply
- The campaign must be active and inside its start and end dates, otherwise the postback is rejected (see errors).
- Daily, monthly and total conversion caps count non-rejected conversions. When a cap is reached, conversions are still recorded but with a zero commission.
- Conversions with a zero commission never create a commission record.
Approval
New conversions start as pending. Registrations follow the campaign's registration approval mode; all other events follow the purchase approval mode.
- Auto-approve: approved immediately and the commission is created, as long as the click's fraud score is below 90. Higher scores stay pending for review.
- Manual review: stays pending until the brand approves or rejects it on the Conversions page.
- Delayed approval: approved automatically once the configured number of days has passed.
- Unauthenticated postbacks accepted in Grace mode always stay pending and are flagged for review; see authentication.
Responses
A 200 response means the conversion was recorded. It does not mean that it earned a commission: status tells you whether it was approved immediately (approved) or waits for review (pending), and authenticated whether your credentials were accepted.
Conversion recorded
HTTP/1.1 200 OK
Content-Type: application/json
{
"success": true,
"message": "Conversion recorded successfully",
"conversion_id": "8d0c2f4e-1a2b-4c3d-9e8f-7a6b5c4d3e2f",
"authenticated": true,
"status": "approved"
}Recorded without valid credentials (Grace mode)
HTTP/1.1 200 OK
Content-Type: application/json
{
"success": true,
"message": "Conversion recorded as pending: postback was not authenticated",
"conversion_id": "8d0c2f4e-1a2b-4c3d-9e8f-7a6b5c4d3e2f",
"authenticated": false,
"status": "pending",
"warning": "Postback is not authenticated. Add token=<your postback secret> (Brand dashboard > Tracking) or an X-MP-Signature header. Unauthenticated conversions are held as pending."
}Registration already recorded for this click
HTTP/1.1 200 OK
Content-Type: application/json
{
"success": true,
"message": "Registration already recorded for this click",
"conversion_id": "8d0c2f4e-1a2b-4c3d-9e8f-7a6b5c4d3e2f",
"authenticated": true
}conversion_id is the MassPartner conversion UUID. Store it next to your order if you want to reference it in support requests.
Errors
Errors return "success": false and a human-readable message.
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"success": false,
"message": "Click not found"
}| Status | Message | Cause and fix |
|---|---|---|
| 400 | Invalid brand ID | The brand ID in the path is not a UUID. Copy the postback URL from the Tracking page. |
| 404 | Brand not found | No brand exists with this ID. |
| 400 | Missing required parameters: click_id, event | click_id or event is missing or empty. With POST, make sure the body is form-encoded, not JSON. |
| 400 | Click not found | The click ID does not exist or belongs to another brand. Check the brand ID in the URL and that you read the cookie on the domain where the visitor landed. |
| 400 | Campaign not found | The click has no campaign and the brand has no active campaign to fall back to. |
| 400 | Campaign is not active (status: paused) | The campaign is paused or still a draft; the current status is shown in brackets. Activate it on the Campaigns page. |
| 400 | Campaign has not started yet | The postback arrived before the campaign's start date and time. |
| 400 | Campaign has ended | The postback arrived after the campaign's end date and time. |
| 401 | Invalid or missing postback token | Strict mode is on and the request has no valid token or signature, or the signature timestamp is more than 300 seconds off. No conversion is recorded. |
| 404 | Brand ID not found in URL | The path is missing the brand ID. |
Retries. Do not repeat a request that returned 400 or 401 without fixing it. Because order_id is not de-duplicated, retry a sale only when you received no response at all (timeout or network error), not after a 200.
Authentication: modes and credentials
Each brand has a postback secret, a 64-character random string. Find it in the Postback authentication section of the Tracking page in the brand dashboard: reveal or copy the secret, copy the Full URL template with your token already filled in, regenerate the secret, and choose the mode. The section also shows how many unauthenticated postbacks arrived in the last 30 days.
| Mode | Requests without valid credentials |
|---|---|
| Grace (default) | Still recorded, but the conversion is always left pending (never auto-approved) and flagged as an unauthenticated postback for your review. The response contains "authenticated": false and a warning. Authenticated postbacks behave normally. |
| Strict | Rejected with HTTP 401; no conversion is recorded. |
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"success": false,
"message": "Invalid or missing postback token"
}Send one of two credentials with every postback:
- Token: the secret itself as the
tokenparameter. Simplest to set up. - HMAC signature: an
X-MP-Signatureheader. The secret never travels over the wire and each signature expires after 300 seconds.
Rotating the secret
Regenerating creates a new secret immediately and the previous one stops working, so requests that still use it count as unauthenticated. To rotate without losing conversions, switch to Grace, regenerate, deploy the new secret to your servers, then switch back to Strict.
Token
Add token=YOUR_POSTBACK_SECRET to the query string or the form body. Prefer POST: a token in the query string ends up in URLs and access logs.
curl
curl -sS -X POST "https://masspartner.com/api/postback/YOUR_BRAND_ID" \
--data-urlencode "token=YOUR_POSTBACK_SECRET" \
--data-urlencode "click_id=3f2b8c1d9e4a5b6c7d8e9f0a1b2c3d4e" \
--data-urlencode "event=sale" \
--data-urlencode "amount=49.99" \
--data-urlencode "currency=USD" \
--data-urlencode "order_id=ORD-1001" \
--data-urlencode "user_id=CUST-42"PHP
<?php
$brandId = 'YOUR_BRAND_ID';
$secret = getenv('MASSPARTNER_POSTBACK_SECRET');
$params = [
'token' => $secret,
'click_id' => $clickId, // from the mp_click cookie or your user record
'event' => 'sale',
'amount' => '49.99',
'currency' => 'USD',
'order_id' => $orderId,
'user_id' => $customerId,
];
$ch = curl_init('https://masspartner.com/api/postback/' . rawurlencode($brandId));
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);
$result = json_decode((string) $body, true);
if ($status !== 200 || empty($result['success'])) {
error_log('MassPartner postback failed: HTTP ' . $status . ' ' . ($result['message'] ?? ''));
}Node.js
// Node.js 18+ (built-in fetch)
const BRAND_ID = 'YOUR_BRAND_ID';
const SECRET = process.env.MASSPARTNER_POSTBACK_SECRET;
async function sendPostback({ clickId, event, amount, currency, orderId, userId }) {
const body = new URLSearchParams({ token: SECRET, click_id: clickId, event });
if (amount !== undefined) body.set('amount', String(amount));
if (currency) body.set('currency', currency);
if (orderId) body.set('order_id', orderId);
if (userId) body.set('user_id', userId);
const res = await fetch(`https://masspartner.com/api/postback/${BRAND_ID}`, {
method: 'POST',
body, // sent as application/x-www-form-urlencoded
signal: AbortSignal.timeout(5000),
});
const data = await res.json();
if (!res.ok || !data.success) {
console.error('MassPartner postback failed:', res.status, data.message);
}
return data;
}HMAC signature
Instead of sending the secret, sign the request and send the signature in a header:
X-MP-Signature: t=<unix seconds>,v1=<hex signature>- Take every parameter you send (query string and body), except
token. - Sort them by name in ascending byte order.
- Encode each name and value per RFC 3986: unreserved characters (
A-Z a-z 0-9 - . _ ~) stay as they are, everything else is percent-encoded with uppercase hex, and a space becomes%20. In PHP userawurlencode(); in JavaScript useencodeURIComponent()and also encode! ' ( ) *. - Join the pairs as
name=valuewith&. This is the canonical query. - Build the message
<t>.<canonical query>, wheretis the current Unix time in seconds. - Compute HMAC-SHA256 of the message with your postback secret (used as-is, as text) as the key, and hex-encode it in lowercase. That is
v1. - Send
X-MP-Signature: t=<t>,v1=<v1>.
MassPartner rebuilds the canonical query from the parameters it receives and compares signatures in constant time. Use plain parameter names (letters, digits, underscore) and no array parameters. Requests whose t differs from the server time by more than 300 seconds are rejected, so keep your server clock synchronised (NTP). The simplest way to avoid encoding mismatches is to send the canonical query itself as the query string, as in the examples.
curl
BRAND_ID="YOUR_BRAND_ID"
SECRET="YOUR_POSTBACK_SECRET"
# Canonical query: parameters sorted by name, RFC 3986-encoded, joined with &
QUERY="amount=49.99&click_id=3f2b8c1d9e4a5b6c7d8e9f0a1b2c3d4e¤cy=USD&event=sale&order_id=ORD-1001&user_id=CUST-42"
T=$(date +%s)
SIG=$(printf '%s.%s' "$T" "$QUERY" | openssl dgst -sha256 -hmac "$SECRET" -r | cut -d' ' -f1)
curl -sS "https://masspartner.com/api/postback/$BRAND_ID?$QUERY" \
-H "X-MP-Signature: t=$T,v1=$SIG"PHP
<?php
$brandId = 'YOUR_BRAND_ID';
$secret = getenv('MASSPARTNER_POSTBACK_SECRET');
$params = [
'click_id' => $clickId,
'event' => 'sale',
'amount' => '49.99',
'currency' => 'USD',
'order_id' => $orderId,
'user_id' => $customerId,
];
// 1. Canonical query: every parameter except token, sorted by name, RFC 3986-encoded
unset($params['token']);
ksort($params, SORT_STRING);
$pairs = [];
foreach ($params as $name => $value) {
$pairs[] = rawurlencode($name) . '=' . rawurlencode((string) $value);
}
$canonical = implode('&', $pairs);
// 2. Sign "<t>.<canonical query>" with HMAC-SHA256
$t = time();
$sig = hash_hmac('sha256', $t . '.' . $canonical, $secret);
// 3. Send the canonical query as the query string, plus the signature header
$ch = curl_init('https://masspartner.com/api/postback/' . rawurlencode($brandId) . '?' . $canonical);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CONNECTTIMEOUT => 5,
CURLOPT_TIMEOUT => 5,
CURLOPT_HTTPHEADER => ['X-MP-Signature: t=' . $t . ',v1=' . $sig],
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);Node.js
// Node.js 18+ (built-in fetch and crypto)
const crypto = require('crypto');
const BRAND_ID = 'YOUR_BRAND_ID';
const SECRET = process.env.MASSPARTNER_POSTBACK_SECRET;
// RFC 3986: encodeURIComponent leaves ! ' ( ) * unescaped, so escape them as well
const rfc3986 = (s) => encodeURIComponent(String(s))
.replace(/[!'()*]/g, (c) => '%' + c.charCodeAt(0).toString(16).toUpperCase());
async function sendSignedPostback(params) {
const canonical = Object.keys(params)
.filter((name) => name !== 'token')
.sort()
.map((name) => `${rfc3986(name)}=${rfc3986(params[name])}`)
.join('&');
const t = Math.floor(Date.now() / 1000);
const v1 = crypto.createHmac('sha256', SECRET).update(`${t}.${canonical}`).digest('hex');
const res = await fetch(`https://masspartner.com/api/postback/${BRAND_ID}?${canonical}`, {
headers: { 'X-MP-Signature': `t=${t},v1=${v1}` },
signal: AbortSignal.timeout(5000),
});
return res.json();
}
// sendSignedPostback({ click_id: clickId, event: 'sale', amount: '49.99', currency: 'USD', order_id: 'ORD-1001', user_id: 'CUST-42' });Signature test vector
Use these values to check your implementation offline. A live request with this timestamp would be rejected as expired.
secret mp_test_secret_0123456789abcdef
t 1760000000
params event=sale, click_id=3f2b8c1d9e4a5b6c7d8e9f0a1b2c3d4e, amount=49.99,
currency=USD, order_id=ORD-1001, user_id="CUST 42"
canonical amount=49.99&click_id=3f2b8c1d9e4a5b6c7d8e9f0a1b2c3d4e¤cy=USD&event=sale&order_id=ORD-1001&user_id=CUST%2042
message 1760000000.amount=49.99&click_id=3f2b8c1d9e4a5b6c7d8e9f0a1b2c3d4e¤cy=USD&event=sale&order_id=ORD-1001&user_id=CUST%2042
v1 b0d875f0df1833b1f244dc622fc90afcd5d9857b89c241979a4f5f08d940427d
header X-MP-Signature: t=1760000000,v1=b0d875f0df1833b1f244dc622fc90afcd5d9857b89c241979a4f5f08d940427dCallbacks
Callbacks let affiliates forward their conversions to their own tracker or server. Affiliates create them on the Callbacks page of the affiliate dashboard with a name, a callback URL, a request method and the events to send.
Events
| Event | Sent when |
|---|---|
| Conversion created | A new conversion is recorded for you, usually with status pending. |
| Conversion approved | A conversion is approved by the brand, automatically or after the approval delay. |
| Conversion rejected | The brand rejects a conversion. |
| Sale (every sale) | A sale-type conversion is approved, for every sale of the customer. |
| First sale | The first approved sale of a customer. |
| Recurring sale | An approved sale after the customer's first one. |
| Refund | A conversion is marked as refunded and its unpaid commission is cancelled. |
If one callback subscribes to several events that match the same approval (for example Conversion approved and Sale), it is called once, with the most specific event. Click events are not sent.
Request format
- GET: we call your callback URL with the placeholders replaced by URL-encoded values.
- POST: we call your URL (placeholders replaced) with a JSON body (
Content-Type: application/json) containing the fields shown below. - The URL must use
httporhttpsand point to a public host; private and reserved network addresses are refused. - Requests are sent right after the conversion changes, with a 3-second connect timeout and a 5-second total timeout. Any
2xxstatus counts as delivered. Timeouts, network errors,5xx,408and429are retried after 5 minutes, 30 minutes and 2 hours; other4xxresponses are not retried. - The Callbacks page shows the number of calls, failures and the last error for each callback, and Send test sends a sample request.
- A failing callback never blocks or changes the conversion.
GET example
https://tracker.example.com/postback?subid={$sub1}&payout={$commission}¤cy={$currency}&status={$status}&txid={$orderid}POST body
POST /your/endpoint HTTP/1.1
Content-Type: application/json
{
"click_id": "3f2b8c1d-9e4a-5b6c-7d8e-9f0a1b2c3d4e",
"affiliate_id": "A3F9C21B",
"campaign_id": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
"conversion_id": "8d0c2f4e-1a2b-4c3d-9e8f-7a6b5c4d3e2f",
"event": "first_sale",
"order_id": "ORD-1001",
"sale_amount": 49.99,
"commission": 10,
"currency": "USD",
"country": "DE",
"status": "approved",
"timestamp": 1760000000,
"sub1": "fb_campaign_12",
"sub2": "adset_7",
"sub3": "",
"sub4": "",
"sub5": ""
}sale_amount, commission and timestamp (Unix seconds of the call) are JSON numbers; the other fields are strings, empty when there is no value.
Callback placeholders
MassPartner placeholders start with a dollar sign, {$name}, so they do not clash with your tracker's own macros such as {clickid}. Names are case-insensitive; unknown placeholders are left as they are.
| Placeholder | Value | Example |
|---|---|---|
{$clickid} | MassPartner ID of the attributed click | 3f2b8c1d-… |
{$sub1} to {$sub5} | The sub IDs from your tracking link. Pass your tracker's own click ID in one of them. | fb_campaign_12 |
{$commission} | Your commission for the conversion | 10.00 |
{$saleamount} | Sale amount reported by the brand (0 when none) | 49.99 |
{$currency} | ISO currency code | USD |
{$status} | Conversion status: pending, approved, rejected or refunded | approved |
{$orderid} | The brand's order ID, when the brand sends one | ORD-1001 |
{$affiliateid} | Your MassPartner affiliate code | A3F9C21B |
{$event} | The event that triggered the call | first_sale |
{$conversionid} | MassPartner conversion ID | 8d0c2f4e-… |
{$conversiontype} | Conversion type: registration, sale, deposit, lead and so on | sale |
{$campaignid} | Campaign ID | 0a1b2c3d-… |
{$productid} | Product ID sent by the brand | PRO-12 |
{$country} | Customer country from the click | DE |
{$timestamp} | Unix time of the call | 1760000000 |
Ad platform exports
On the Exports page affiliates download their conversions as CSV files for offline conversion import. The ad platform's click ID has to be in one of the sub IDs of the tracking link.
| Option | Values |
|---|---|
| Platform | Google Ads (GCLID) or Microsoft Ads (MSCLKID) |
| Conversion status | Approved only (recommended) or Approved and pending. Rejected and refunded conversions are never exported. |
| Date range | UTC days within the last 90 days, the ad platforms' import window |
| Click ID stored in | sub1 to sub5. Rows without a valid click ID there are skipped. |
| Conversion action name | Default affiliate_sale. Must match the conversion action or goal in the ad account exactly, including capitalisation. |
| Conversion value | Your commission amount, or the sale amount reported by the brand (left blank when missing, so the platform uses the action's default value) |
File format
Both files start with the row Parameters:TimeZone=+0000, and every conversion time is written in UTC as yyyy-MM-dd HH:mm:ss+0000, for example 2026-10-01 13:00:00+0000.
| Platform | Click ID to pass | Columns |
|---|---|---|
| Google Ads | {gclid} | Google Click ID, Conversion Name, Conversion Time, Conversion Value, Conversion Currency |
| Microsoft Ads | {msclkid} | Conversion Name, Conversion Time, Conversion Value, Conversion Currency, Microsoft Click ID, Hashed Email Address, Hashed Phone Number (the hashed columns stay empty) |
The export guide shows how to capture the click ID and set up the matching conversion action in each ad platform.
What is not available
- There is no general REST API with API keys for campaigns, affiliates or reports. The JSON endpoints used by the dashboard require a logged-in session and can change without notice; do not build integrations on them. Use the CSV exports in the dashboard for reporting data.
- Conversions cannot be sent from browser JavaScript with your secret. Use the server-side postback.
- The postback does not accept JSON bodies or batches. Send one request per conversion.
Questions about an integration? Contact us or read the support center.