How verification works
A sale earns commission only when it is verified end to end: the partner’s click is recorded by us, the payment is reported by your server with a signature only you can produce, and both are matched on our side.
A partner shares a tracking link
The link (
/r/…) records a click and redirects to the landing URL of your program withspm_clickappended (andspm_vidfor programs with click stitching).Your site keeps the click id
Store
spm_clickwith the trial or account the visitor creates. A cookie is only a fallback; the server-side id is what counts.Your backend reports the paid invoice
When the customer pays, your server sends
POST /integrations/v1/conversionswith the amounts and the click id (or a coupon / referral code). Browsers never report sales.We check the request
API key, HMAC signature and a ±300 s timestamp window; schema; idempotency on
event_idandexternal_transaction_id; the plan; and the click against our click log and the program cookie window. Deal registrations, coupons and referral codes compete by a fixed precedence.A pending commission is created
For an attributed sale the program rule calculates the commission (integer paise) and it starts as pending. Refunds and chargebacks you report later reverse it proportionally.
It becomes available to the partner
After approval and once the program’s hold period has passed with no holds, it becomes available. When vendor billing is switched on, it also waits until your invoice for it is paid.
Quickstart
- Create a test key. In Vendor → Integrations choose Create key, pick the Test mode and confirm your password (and 2FA code if enabled). You get an
api_key(spm_test_….…) and asigning_secret(whsec_…) — shown once; store them in your secret manager. - Capture
spm_clickon the landing page of your program and keep it with the account the visitor creates. - Send your first event from your server when an invoice is paid — see the signing examples below. Or press Send a test event in Vendor → Integrations to see a signed request and its response without writing code.
- Read the response. In test mode
data.testistrueanddata.resultshows the attribution and acommission_preview; nothing is created. Your test events are listed in Vendor → Integrations with a Test badge. - Switch to live by creating a live key and swapping the two secrets in your configuration. Live events create real conversions and commissions.
// On your landing/signup page (browser)
const params = new URLSearchParams(window.location.search);
const spmClick = params.get('spm_click'); // e.g. "c_8kq2v0x7w1"
const spmVid = params.get('spm_vid'); // only for programs with click stitching
// Store them with the trial/account you create, e.g. in hidden form fields,
// and send them as attribution.click_id / attribution.visitor_id when the customer pays.Authentication & signing
Every request carries three headers:
Authorization: Bearer <api_key>X-SPM-Signature: t=<unix seconds>,v1=<signature>where the signature is the lowercase hexHMAC_SHA256(signing_secret, "<t>.<raw body>")Content-Type: application/json
Sign the exact bytes you send: serialise the JSON once, sign that string, send that string. Timestamps more than 300 seconds away from our clock are rejected, so keep your server clock in sync. API keys are stored hashed and signing secrets encrypted; if one leaks, revoke the key in Vendor → Integrations — revoked keys stop working immediately.
# Bash + OpenSSL + curl. BODY is sent byte-for-byte as signed.
BODY='{"event_id":"evt_123","external_transaction_id":"pay_123","event_type":"ONE_TIME","external_plan_id":"lifetime","customer":{"external_customer_id":"cus_1","organization_name":"Acme Pvt Ltd"},"amounts":{"gross":118000,"tax":18000},"occurred_at":"2026-09-01T10:00:00+05:30"}'
T=$(date +%s)
SIG=$(printf '%s' "$T.$BODY" | openssl dgst -sha256 -hmac "$SPM_SIGNING_SECRET" | sed 's/^.*= //')
curl -sS -X POST "$SPM_API_URL/integrations/v1/conversions" \
-H "Authorization: Bearer $SPM_API_KEY" \
-H "X-SPM-Signature: t=$T,v1=$SIG" \
-H 'Content-Type: application/json' \
--data-raw "$BODY"
// Node.js 18+ (built-in fetch and crypto)
const crypto = require('node:crypto');
// rawBody must be exactly the string you send as the request body.
function spmSignature(signingSecret, rawBody, timestamp = Math.floor(Date.now() / 1000)) {
const v1 = crypto.createHmac('sha256', signingSecret).update(`${timestamp}.${rawBody}`).digest('hex');
return `t=${timestamp},v1=${v1}`;
}
async function sendEvent(path, event) {
const rawBody = JSON.stringify(event);
const res = await fetch(`${process.env.SPM_API_URL}/integrations/v1${path}`, {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.SPM_API_KEY}`,
'X-SPM-Signature': spmSignature(process.env.SPM_SIGNING_SECRET, rawBody),
'Content-Type': 'application/json',
},
body: rawBody,
});
return { status: res.status, body: await res.json() };
}
# Python 3 (standard library only)
import hashlib, hmac, json, os, time, urllib.error, urllib.request
def spm_signature(signing_secret, raw_body, timestamp=None):
"""raw_body must be exactly the string you send as the request body."""
t = int(time.time()) if timestamp is None else timestamp
v1 = hmac.new(signing_secret.encode(), f"{t}.{raw_body}".encode(), hashlib.sha256).hexdigest()
return f"t={t},v1={v1}"
def send_event(path, event):
raw_body = json.dumps(event, separators=(",", ":"))
req = urllib.request.Request(
os.environ["SPM_API_URL"] + "/integrations/v1" + path,
data=raw_body.encode(),
method="POST",
headers={
"Authorization": "Bearer " + os.environ["SPM_API_KEY"],
"X-SPM-Signature": spm_signature(os.environ["SPM_SIGNING_SECRET"], raw_body),
"Content-Type": "application/json",
},
)
try:
with urllib.request.urlopen(req) as res:
return res.status, json.load(res)
except urllib.error.HTTPError as err:
return err.code, json.load(err)
<?php
// PHP 7.4+ with the curl extension
// $rawBody must be exactly the string you send as the request body.
function spm_signature(string $signingSecret, string $rawBody, ?int $timestamp = null): string {
$t = $timestamp ?? time();
$v1 = hash_hmac('sha256', $t . '.' . $rawBody, $signingSecret);
return "t={$t},v1={$v1}";
}
function send_event(string $path, array $event): array {
$rawBody = json_encode($event, JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE);
$ch = curl_init(getenv('SPM_API_URL') . '/integrations/v1' . $path);
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => $rawBody,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv('SPM_API_KEY'),
'X-SPM-Signature: ' . spm_signature(getenv('SPM_SIGNING_SECRET'), $rawBody),
'Content-Type: application/json',
],
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
return [$status, json_decode($body, true)];
}
Set SPM_API_URL to the marketplace API origin (the host that serves /api/v1), and SPM_API_KEY / SPM_SIGNING_SECRET to your key. These examples are tested against our signature verifier.
Idempotency & retries
- Every event has an
event_id. Sending the same event again returns the original result withduplicate: true; reusing anevent_idwith a different payload returns 409 IDEMPOTENCY_KEY_REUSED. Retry freely after timeouts. external_transaction_id,external_refund_idand a chargeback’sexternal_referenceare also unique per vendor, so one payment is never counted twice even under a newevent_id.- 200 — processed;
data.resultdescribes the outcome. - 202 — accepted and queued for retry, e.g. a refund that arrived before its payment. We retry with exponential back-off from 30 seconds up to 1 hour between attempts and stop after 6 attempts (dead letter); you can retry dead-lettered events from Vendor → Integrations.
- 400 — the body failed validation and was not stored. 401 — key or signature rejected. 422 — a business rule rejected the event (e.g.
UNKNOWN_PLAN); it is stored as ignored and a resend returns the same rejection. - 429 — more than 600 requests per minute for one API key (requests without a valid key are limited per IP address). Back off and retry.
- Errors use one envelope:
{"success": false, "error": {"code", "message", "details"}, "request_id"}. Quote therequest_idwhen you contact support. - All amounts are integers in minor units (paise for INR). Never send decimals.
Endpoint reference
Base path /integrations/v1. Every endpoint accepts POST with a JSON body and returns {"success": true, "data": {"event_id", "status", "result"}}. Unknown body fields are ignored.
POST/integrations/v1/conversions
Report a payment
A verified payment: a paid invoice, a subscription renewal or an upgrade. This is the only event that can create a commission.
Body fields
event_idstringRequiredUnique id of this event, 1–200 characters. Resending the same event with the same id is safe (idempotency).
external_transaction_idstringRequiredYour payment/transaction id. Unique per vendor: the same payment is never counted twice, even under a new
event_id. Refunds and chargebacks refer to it.external_invoice_idstringoptionalYour identifier, 1–200 characters.
event_typeone of ONE_TIME | INITIAL | RECURRING | EXPANSIONRequiredONE_TIMEpurchase,INITIALfirst subscription payment,RECURRINGrenewal,EXPANSIONupgrade of an existing subscription (send only the incremental amount).product_iduuidoptionalOur product id. Either
product_idorexternal_plan_idis required; passproduct_idwhen one plan id exists on several of your products.external_plan_idstringoptionalThe plan id you set on the plan in Vendor → Products. Either this or
product_idis required.external_subscription_idstringoptionalYour subscription id. Required for
INITIAL,RECURRINGandEXPANSION.customerobjectRequiredThe paying company.
customer.external_customer_idstringRequiredYour customer id, 1–200 characters. Matches later payments and renewals to the same customer.
customer.organization_namestringRequiredCompany name, 1–200 characters. Used for deal-registration matching.
customer.domainstringoptionalCompany website domain, up to 253 characters. Taken from
emailwhen omitted.customer.gstinstringoptionalGSTIN, up to 15 characters. Stored only as a keyed hash.
customer.emailemailoptionalBilling contact email. Stored only as a keyed hash (plus its domain).
customer.phonestringoptionalUp to 20 characters. Stored only as a keyed hash.
amountsobjectRequiredInvoice amounts.
discount + tax + feemay not exceedgross.amounts.grossintegerRequiredInvoice total including tax, before discount. Integer, in minor units (paise for INR; cents for other currencies).
amounts.discountintegeroptionalDefaults to 0. Integer, in minor units (paise for INR; cents for other currencies).
amounts.taxintegeroptionalDefaults to 0. Integer, in minor units (paise for INR; cents for other currencies).
amounts.feeintegeroptionalPayment fees, defaults to 0. Integer, in minor units (paise for INR; cents for other currencies).
currencyone of INR | USD | EUR | GBP | AED | SGD | AUD | CADoptionalDefaults to
INR. Other currencies are converted to INR at the rate for the payment date; refunds and chargebacks must use the currency of the payment.fx_ratenumberoptionalYour INR rate for a foreign-currency payment (greater than 0, at most 100000). Without it the platform rate for the payment date is used.
occurred_atdatetimeRequiredWhen the payment happened. ISO 8601 date-time with a time-zone offset, e.g.
2026-09-01T10:00:00+05:30. At most 5 minutes in the future.attributionobjectoptionalPartner signals you captured. All optional; we verify each one.
attribution.click_idstringoptionalThe
spm_clickvalue from your landing URL, up to 100 characters. Verified against our click log and the program cookie window.attribution.visitor_idstringoptionalThe
spm_vidvalue (v_+ 16–64 URL-safe characters), only for programs with click stitching. Normally read from the click.attribution.coupon_codestringoptionalA partner coupon code used at checkout, up to 60 characters.
attribution.referral_codestringoptionalA partner referral code, up to 60 characters.
attribution.crm_partner_codestringoptionalA partner referral code recorded in your CRM, up to 60 characters (lowest precedence).
- Renewals (
RECURRING) follow the customer’s locked attribution; you do not need to resend the click. - An
EXPANSIONis credited only to the partner the customer is already attributed to and never creates an attribution; whether it earns commission depends on the program rule.
{
"event_id": "evt_123",
"external_transaction_id": "pay_123",
"external_invoice_id": "inv_123",
"event_type": "INITIAL",
"external_plan_id": "pro_monthly",
"external_subscription_id": "sub_123",
"customer": {
"external_customer_id": "cus_1",
"organization_name": "Acme Pvt Ltd",
"domain": "acme.in",
"email": "[email protected]"
},
"amounts": {
"gross": 117882,
"discount": 0,
"tax": 17982,
"fee": 0
},
"currency": "INR",
"occurred_at": "2026-09-01T10:00:00+05:30",
"attribution": {
"click_id": "c_8kq2v0x7w1"
}
}{
"success": true,
"data": {
"event_id": "evt_123",
"status": "PROCESSED",
"result": {
"conversion_id": "6c1f…",
"attribution_status": "ATTRIBUTED",
"attribution_note": null,
"partner_attributed": true,
"commission_id": "0b9e…",
"commission_amount": 19980
}
}
}Result fields
conversion_id- Our id for the payment.
attribution_statusATTRIBUTED,UNATTRIBUTED,EXISTING_CUSTOMERorNOT_ELIGIBLE.attribution_note- Why, when not simply attributed (e.g.
no_eligible_candidate: LINK:outside_cookie_window). partner_attributedtruewhen a partner was credited.commission_id- The pending commission, or
null. commission_amount- In INR paise; 0 when no commission.
commission_note- Present when an attributed payment earned nothing (e.g.
no_applicable_rule,recurring_duration_exceeded,monthly_cap_reached). duplicate_transaction- Present (
true) when thisexternal_transaction_idwas already reported; nothing new is created.
Errors
- 400 VALIDATION_FAILEDThe body does not match the schema (
error.details.issueslists the fields). Not stored; fix and resend. - 401 API_KEY_INVALIDMissing, unknown, revoked or expired API key.
- 401 SIGNATURE_INVALIDMissing or malformed
X-SPM-Signature, wrong signature, or a timestamp more than 300 s from our clock. - 409 IDEMPOTENCY_KEY_REUSED
event_idwas already used for a different payload or endpoint. - 429 RATE_LIMITEDMore than 600 requests in a minute for this API key.
- 422 UNKNOWN_PLAN
external_plan_idis not a plan of yours. - 422 AMBIGUOUS_PLANThe plan id exists on several of your products; send
product_idtoo. - 422 UNKNOWN_PRODUCT
product_idis not a product of yours. - 422 OCCURRED_AT_IN_FUTURE
occurred_atis more than 5 minutes ahead. - 422 FX_RATE_MISSINGForeign currency without
fx_rateand no platform rate for that date.
POST/integrations/v1/refunds
Report a refund
Reverses commission in proportion to the cumulative refunded share of the amount paid (gross − discount). Total refunds can never exceed the amount paid.
Body fields
event_idstringRequiredUnique id of this event, 1–200 characters. Resending the same event with the same id is safe (idempotency).
external_refund_idstringRequiredYour refund id. Unique per vendor: a resent refund is never applied twice.
external_transaction_idstringRequiredThe payment being refunded (as sent to
/conversions).amountintegerRequiredRefunded amount, greater than 0. Integer, in minor units (paise for INR; cents for other currencies).
currencyone of INR | USD | EUR | GBP | AED | SGD | AUD | CADoptionalDefaults to
INR. Other currencies are converted to INR at the rate for the payment date; refunds and chargebacks must use the currency of the payment.reasonstringoptionalUp to 500 characters.
occurred_atdatetimeRequiredISO 8601 date-time with a time-zone offset, e.g.
2026-09-01T10:00:00+05:30.
- A refund that arrives before its payment is accepted with
202and retried automatically (see Idempotency & retries).
{
"event_id": "evt_124",
"external_refund_id": "rf_77",
"external_transaction_id": "pay_123",
"amount": 29470,
"currency": "INR",
"reason": "Seat reduction",
"occurred_at": "2026-09-10T12:00:00+05:30"
}{
"success": true,
"data": {
"event_id": "evt_124",
"status": "PROCESSED",
"result": {
"refund_id": "9a4d…",
"commission_reversed": 4995
}
}
}Result fields
refund_id- Our id for the refund.
commission_reversed- Commission reversed by this refund, in INR paise.
duplicate_refund- Present (
true) when thisexternal_refund_idwas already applied.
Errors
- 400 VALIDATION_FAILEDThe body does not match the schema (
error.details.issueslists the fields). Not stored; fix and resend. - 401 API_KEY_INVALIDMissing, unknown, revoked or expired API key.
- 401 SIGNATURE_INVALIDMissing or malformed
X-SPM-Signature, wrong signature, or a timestamp more than 300 s from our clock. - 409 IDEMPOTENCY_KEY_REUSED
event_idwas already used for a different payload or endpoint. - 429 RATE_LIMITEDMore than 600 requests in a minute for this API key.
- 422 REFUND_EXCEEDS_PAYMENTThis refund would take total refunds above the amount paid.
- 422 CURRENCY_MISMATCHThe refund currency differs from the payment’s.
POST/integrations/v1/chargebacks
Report a chargeback
OPEN holds the payment’s commission, LOST reverses it in proportion to the disputed amount, WON releases the hold. Send the same external_reference for each status change.
Body fields
event_idstringRequiredUnique id of this event, 1–200 characters. Resending the same event with the same id is safe (idempotency).
external_referencestringRequiredYour chargeback/dispute id. Once it is
WONorLOST, later updates are ignored.external_transaction_idstringRequiredThe disputed payment.
amountintegerRequiredDisputed amount, greater than 0. Integer, in minor units (paise for INR; cents for other currencies).
currencyone of INR | USD | EUR | GBP | AED | SGD | AUD | CADoptionalDefaults to
INR. Other currencies are converted to INR at the rate for the payment date; refunds and chargebacks must use the currency of the payment.statusone of OPEN | WON | LOSTRequiredCurrent state of the chargeback.
occurred_atdatetimeRequiredISO 8601 date-time with a time-zone offset, e.g.
2026-09-01T10:00:00+05:30.
{
"event_id": "evt_125",
"external_reference": "cb_31",
"external_transaction_id": "pay_123",
"amount": 117882,
"currency": "INR",
"status": "OPEN",
"occurred_at": "2026-09-12T09:30:00+05:30"
}{
"success": true,
"data": {
"event_id": "evt_125",
"status": "PROCESSED",
"result": {
"chargeback_id": "3e2a…",
"status": "OPEN",
"commission_reversed": 0
}
}
}Result fields
chargeback_id- Our id for the chargeback.
status- The status applied.
commission_reversed- Commission reversed (only for
LOST), in INR paise. ignored- Present when the chargeback was already closed (
chargeback already WON).
Errors
- 400 VALIDATION_FAILEDThe body does not match the schema (
error.details.issueslists the fields). Not stored; fix and resend. - 401 API_KEY_INVALIDMissing, unknown, revoked or expired API key.
- 401 SIGNATURE_INVALIDMissing or malformed
X-SPM-Signature, wrong signature, or a timestamp more than 300 s from our clock. - 409 IDEMPOTENCY_KEY_REUSED
event_idwas already used for a different payload or endpoint. - 429 RATE_LIMITEDMore than 600 requests in a minute for this API key.
- 422 CURRENCY_MISMATCHThe chargeback currency differs from the payment’s.
POST/integrations/v1/subscriptions/events
Report a subscription change
Cancellation, reactivation or past-due state of a subscription you reported with a payment. Events older than the last applied change are ignored.
Body fields
event_idstringRequiredUnique id of this event, 1–200 characters. Resending the same event with the same id is safe (idempotency).
typeone of CANCELLED | REACTIVATED | PAST_DUERequiredWhat happened. What a reactivation earns follows the program’s reactivation policy.
external_subscription_idstringRequiredThe subscription, as sent with its payments.
occurred_atdatetimeRequiredISO 8601 date-time with a time-zone offset, e.g.
2026-09-01T10:00:00+05:30.
- An event for a subscription we have not seen yet is accepted with
202and retried.
{
"event_id": "evt_126",
"type": "CANCELLED",
"external_subscription_id": "sub_123",
"occurred_at": "2026-10-01T00:00:00+05:30"
}{
"success": true,
"data": {
"event_id": "evt_126",
"status": "PROCESSED",
"result": {
"subscription_id": "5d0c…",
"status": "CANCELLED"
}
}
}Result fields
subscription_id- Our id for the subscription.
statusCANCELLED,REACTIVATEDorPAST_DUE.ignoredstale_eventwhen a newer change was already applied.
Errors
- 400 VALIDATION_FAILEDThe body does not match the schema (
error.details.issueslists the fields). Not stored; fix and resend. - 401 API_KEY_INVALIDMissing, unknown, revoked or expired API key.
- 401 SIGNATURE_INVALIDMissing or malformed
X-SPM-Signature, wrong signature, or a timestamp more than 300 s from our clock. - 409 IDEMPOTENCY_KEY_REUSED
event_idwas already used for a different payload or endpoint. - 429 RATE_LIMITEDMore than 600 requests in a minute for this API key.
POST/integrations/v1/customers
Create or update a customer
Optional. Tells us about a customer before it pays, so deal registrations can be matched and conflicts detected. Payments upsert the customer anyway.
Body fields
event_idstringRequiredUnique id of this event, 1–200 characters. Resending the same event with the same id is safe (idempotency).
customerobjectRequiredThe company.
customer.external_customer_idstringRequiredYour customer id, 1–200 characters. Matches later payments and renewals to the same customer.
customer.organization_namestringRequiredCompany name, 1–200 characters. Used for deal-registration matching.
customer.domainstringoptionalCompany website domain, up to 253 characters. Taken from
emailwhen omitted.customer.gstinstringoptionalGSTIN, up to 15 characters. Stored only as a keyed hash.
customer.emailemailoptionalBilling contact email. Stored only as a keyed hash (plus its domain).
customer.phonestringoptionalUp to 20 characters. Stored only as a keyed hash.
{
"event_id": "evt_127",
"customer": {
"external_customer_id": "cus_1",
"organization_name": "Acme Pvt Ltd",
"domain": "acme.in",
"gstin": "27AAPFU0939F1ZV"
}
}{
"success": true,
"data": {
"event_id": "evt_127",
"status": "PROCESSED",
"result": {
"customer_id": "7f1b…",
"created": true
}
}
}Result fields
customer_id- Our id for the customer.
createdtruefor a new customer,falsefor an update.
Errors
- 400 VALIDATION_FAILEDThe body does not match the schema (
error.details.issueslists the fields). Not stored; fix and resend. - 401 API_KEY_INVALIDMissing, unknown, revoked or expired API key.
- 401 SIGNATURE_INVALIDMissing or malformed
X-SPM-Signature, wrong signature, or a timestamp more than 300 s from our clock. - 409 IDEMPOTENCY_KEY_REUSED
event_idwas already used for a different payload or endpoint. - 429 RATE_LIMITEDMore than 600 requests in a minute for this API key.
POST/integrations/v1/leads
Record a lead for a partner
A lead your CRM attributes to a partner. The partner must be approved in one of your programs for the product.
Body fields
event_idstringRequiredUnique id of this event, 1–200 characters. Resending the same event with the same id is safe (idempotency).
partner_codestringRequiredThe partner’s referral code, up to 60 characters.
product_iduuidRequiredOur product id.
company_namestringRequired2–160 characters.
contact_namestringRequired1–120 characters.
contact_emailemailRequiredLead contact email.
{
"event_id": "evt_128",
"partner_code": "growth1a2b3c",
"product_id": "4b7c2f0e-3d1a-4c8e-9f60-1a2b3c4d5e6f",
"company_name": "Globex India",
"contact_name": "Priya Nair",
"contact_email": "[email protected]"
}{
"success": true,
"data": {
"event_id": "evt_128",
"status": "PROCESSED",
"result": {
"lead_id": "2c6d…"
}
}
}Result fields
lead_id- Our id for the lead (status
ACCEPTED).
Errors
- 400 VALIDATION_FAILEDThe body does not match the schema (
error.details.issueslists the fields). Not stored; fix and resend. - 401 API_KEY_INVALIDMissing, unknown, revoked or expired API key.
- 401 SIGNATURE_INVALIDMissing or malformed
X-SPM-Signature, wrong signature, or a timestamp more than 300 s from our clock. - 409 IDEMPOTENCY_KEY_REUSED
event_idwas already used for a different payload or endpoint. - 429 RATE_LIMITEDMore than 600 requests in a minute for this API key.
- 404 NOT_FOUNDNo partner with that code is approved in a program for the product.
POST/integrations/v1/crm/events
Report a CRM stage change
Moves a partner lead when its stage changes in your CRM. Map stages to lead statuses in Vendor → Integrations → CRM sync.
Body fields
event_idstringRequiredUnique id of this event, 1–200 characters. Resending the same event with the same id is safe (idempotency).
typeone of lead.stage_changedRequiredAlways
lead.stage_changed.spm_iduuidoptionalOur lead id (from our CRM webhook). Either
spm_idorexternal_idis required.external_idstringoptionalYour CRM record id, once your receiver returned it to us. Either this or
spm_idis required.stagestringRequiredYour CRM stage name, 1–100 characters.
occurred_atdatetimeRequiredISO 8601 date-time with a time-zone offset, e.g.
2026-09-01T10:00:00+05:30.
{
"event_id": "crm_evt_123",
"type": "lead.stage_changed",
"spm_id": "8d3f6a2e-1b4c-4d5e-8f70-9a0b1c2d3e4f",
"stage": "Sales Qualified",
"occurred_at": "2026-09-27T10:00:00+05:30"
}{
"success": true,
"data": {
"event_id": "crm_evt_123",
"status": "PROCESSED",
"result": {
"lead_id": "8d3f6a2e-1b4c-4d5e-8f70-9a0b1c2d3e4f",
"status": "QUALIFIED"
}
}
}Result fields
lead_id- Our lead id.
status- The lead status applied.
unchangedtruewhen the lead already had that status.ignoredunmapped_stageorinvalid_transition; the event is acknowledged and nothing changes.
Errors
- 400 VALIDATION_FAILEDThe body does not match the schema (
error.details.issueslists the fields). Not stored; fix and resend. - 401 API_KEY_INVALIDMissing, unknown, revoked or expired API key.
- 401 SIGNATURE_INVALIDMissing or malformed
X-SPM-Signature, wrong signature, or a timestamp more than 300 s from our clock. - 409 IDEMPOTENCY_KEY_REUSED
event_idwas already used for a different payload or endpoint. - 429 RATE_LIMITEDMore than 600 requests in a minute for this API key.
- 400 LEAD_NOT_FOUNDNo lead of yours matches
spm_id/external_id.
Test mode
Requests signed with a test key go through exactly the same checks as live ones — key, signature, timestamp window, rate limit, schema, plan lookup, amount rules and click verification against the real click log — and return the outcome a live event would produce. Nothing is created: no customer, conversion, attribution, commission, ledger entry, notification or CRM update.
- The response has
test: true;result.commission_previewshows the amount, the calculation base, the rule and the hold that would apply, andresult.attribution_previewthe partner that would be credited. - Test events are idempotent separately from live ones: the same
event_idcan be used once in each mode. - Refunds, chargebacks and subscription changes sent with a test key are checked against your earlier test payments, never live ones.
- Because nothing is stored, a test renewal does not see the attribution of an earlier test payment; it is evaluated against your live data only.
- Test events appear in Vendor → Integrations with a Test badge and can be filtered. They are never retried.
{
"success": true,
"data": {
"event_id": "evt_test_1",
"status": "PROCESSED",
"test": true,
"result": {
"conversion_id": null,
"attribution_status": "ATTRIBUTED",
"attribution_note": null,
"partner_attributed": true,
"commission_id": null,
"commission_amount": 19980,
"commission_preview": {
"amount": 19980,
"base": 99900,
"currency": "INR",
"status": "PENDING",
"rule": {
"id": "a3c1…",
"version": 1,
"base_type": "TAX_EXCLUSIVE",
"calculation_type": "PERCENTAGE",
"rate_bps": 2000,
"fixed_amount": null,
"duration_months": null,
"expansion_policy": null
},
"hold_days": 30,
"hold_until": "2026-10-01T04:30:00.000Z",
"frozen_reason": null,
"capped_by_monthly_cap": false,
"capped_by_lifetime_cap": false
},
"attribution_preview": {
"type": "LINK",
"partner_id": "5b2e…",
"program_id": "91d0…",
"existing": false
},
"candidates": [
{
"type": "LINK",
"partner_id": "5b2e…",
"program_id": "91d0…",
"eligible": true,
"rejected_because": null
}
],
"customer": {
"customer_id": null,
"existing": false
}
}
}
}Webhooks we send (CRM)
When you connect a CRM with the generic webhook in Vendor → Integrations → CRM sync, we POST JSON {event, id, occurred_at, data} to your HTTPS endpoint for LEAD_CREATED, LEAD_UPDATED, DEAL_SUBMITTED, DEAL_APPROVED (the events you selected).
- Each request is signed with the connection’s signing secret in the same
X-SPM-Signature: t=…,v1=…format — verify it exactly as we verify yours, and reject old timestamps. - Respond with a 2xx status within 10 seconds. You may return
{"external_id": "…"}(up to 200 characters) to link your CRM record; use it later asexternal_idin CRM stage changes. - Failed deliveries are retried after 1 minute, 5 minutes, 30 minutes, 2 hours, 12 hours, then marked dead; you can retry them from the portal.
- Changes that came from your CRM are never sent back to it.
{
"event": "LEAD_CREATED",
"id": "0f6e…",
"occurred_at": "2026-09-27T04:30:00.000Z",
"data": {
"spm_id": "8d3f6a2e-1b4c-4d5e-8f70-9a0b1c2d3e4f",
"type": "lead",
"status": "NEW",
"company_name": "Globex India",
"company_domain": "globex.in",
"contact_name": "Priya Nair",
"contact_email": "[email protected]",
"contact_phone": null,
"expected_value": null,
"expected_close_date": null,
"program": {
"id": "91d0…",
"name": "Acme Partner Program"
},
"partner": {
"id": "5b2e…",
"name": "Growth Partners",
"referral_code": "growth1a2b3c"
},
"external_id": null
}
}Changelog & versioning
The version is part of the base path (/integrations/v1). Responses may gain new fields; ignore fields you do not recognise.
Test mode
TEST API keys evaluate events without creating customers, conversions or commissions, and return a
commission_preview. Test events appear in the event log with a Test badge.Upgrades and click stitching
event_type: EXPANSIONfor subscription upgrades, andattribution.visitor_idfor programs that stitch several clicks of one visitor.CRM sync
POST /crm/eventsand signed outbound CRM webhooks for leads and deals.
Questions about an integration? Contact us or open a support ticket from the vendor portal.