Skip to content
Shubh Partner

Developers

Integration API

Your backend reports verified payments, refunds, chargebacks and subscription changes over a signed server-to-server API. Commissions are only ever created from these events — never from a browser.

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.

  1. A partner shares a tracking link

    The link (/r/…) records a click and redirects to the landing URL of your program with spm_click appended (and spm_vid for programs with click stitching).

  2. Your site keeps the click id

    Store spm_click with the trial or account the visitor creates. A cookie is only a fallback; the server-side id is what counts.

  3. Your backend reports the paid invoice

    When the customer pays, your server sends POST /integrations/v1/conversions with the amounts and the click id (or a coupon / referral code). Browsers never report sales.

  4. We check the request

    API key, HMAC signature and a ±300 s timestamp window; schema; idempotency on event_id and external_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.

  5. 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.

  6. 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

  1. 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 a signing_secret (whsec_…) — shown once; store them in your secret manager.
  2. Capture spm_click on the landing page of your program and keep it with the account the visitor creates.
  3. 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.
  4. Read the response. In test mode data.test is true and data.result shows the attribution and a commission_preview; nothing is created. Your test events are listed in Vendor → Integrations with a Test badge.
  5. Switch to live by creating a live key and swapping the two secrets in your configuration. Live events create real conversions and commissions.
landing-page.js
// 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 hex HMAC_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.

send-event.sh
# 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"

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 with duplicate: true; reusing an event_id with a different payload returns 409 IDEMPOTENCY_KEY_REUSED. Retry freely after timeouts.
  • external_transaction_id, external_refund_id and a chargeback’s external_reference are also unique per vendor, so one payment is never counted twice even under a new event_id.
  • 200 — processed; data.result describes 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 the request_id when 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_idstringRequired

    Unique id of this event, 1–200 characters. Resending the same event with the same id is safe (idempotency).

  • external_transaction_idstringRequired

    Your 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_idstringoptional

    Your identifier, 1–200 characters.

  • event_typeone of ONE_TIME | INITIAL | RECURRING | EXPANSIONRequired

    ONE_TIME purchase, INITIAL first subscription payment, RECURRING renewal, EXPANSION upgrade of an existing subscription (send only the incremental amount).

  • product_iduuidoptional

    Our product id. Either product_id or external_plan_id is required; pass product_id when one plan id exists on several of your products.

  • external_plan_idstringoptional

    The plan id you set on the plan in Vendor → Products. Either this or product_id is required.

  • external_subscription_idstringoptional

    Your subscription id. Required for INITIAL, RECURRING and EXPANSION.

  • customerobjectRequired

    The paying company.

  • customer.external_customer_idstringRequired

    Your customer id, 1–200 characters. Matches later payments and renewals to the same customer.

  • customer.organization_namestringRequired

    Company name, 1–200 characters. Used for deal-registration matching.

  • customer.domainstringoptional

    Company website domain, up to 253 characters. Taken from email when omitted.

  • customer.gstinstringoptional

    GSTIN, up to 15 characters. Stored only as a keyed hash.

  • customer.emailemailoptional

    Billing contact email. Stored only as a keyed hash (plus its domain).

  • customer.phonestringoptional

    Up to 20 characters. Stored only as a keyed hash.

  • amountsobjectRequired

    Invoice amounts. discount + tax + fee may not exceed gross.

  • amounts.grossintegerRequired

    Invoice total including tax, before discount. Integer, in minor units (paise for INR; cents for other currencies).

  • amounts.discountintegeroptional

    Defaults to 0. Integer, in minor units (paise for INR; cents for other currencies).

  • amounts.taxintegeroptional

    Defaults to 0. Integer, in minor units (paise for INR; cents for other currencies).

  • amounts.feeintegeroptional

    Payment fees, defaults to 0. Integer, in minor units (paise for INR; cents for other currencies).

  • currencyone of INR | USD | EUR | GBP | AED | SGD | AUD | CADoptional

    Defaults 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_ratenumberoptional

    Your 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_atdatetimeRequired

    When 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.

  • attributionobjectoptional

    Partner signals you captured. All optional; we verify each one.

  • attribution.click_idstringoptional

    The spm_click value from your landing URL, up to 100 characters. Verified against our click log and the program cookie window.

  • attribution.visitor_idstringoptional

    The spm_vid value (v_ + 16–64 URL-safe characters), only for programs with click stitching. Normally read from the click.

  • attribution.coupon_codestringoptional

    A partner coupon code used at checkout, up to 60 characters.

  • attribution.referral_codestringoptional

    A partner referral code, up to 60 characters.

  • attribution.crm_partner_codestringoptional

    A 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 EXPANSION is 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.
Request · /conversions
{
  "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"
  }
}
Response · 200
{
  "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_status
ATTRIBUTED, UNATTRIBUTED, EXISTING_CUSTOMER or NOT_ELIGIBLE.
attribution_note
Why, when not simply attributed (e.g. no_eligible_candidate: LINK:outside_cookie_window).
partner_attributed
true when 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 this external_transaction_id was already reported; nothing new is created.

Errors

  • 400 VALIDATION_FAILEDThe body does not match the schema (error.details.issues lists 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_REUSEDevent_id was already used for a different payload or endpoint.
  • 429 RATE_LIMITEDMore than 600 requests in a minute for this API key.
  • 422 UNKNOWN_PLANexternal_plan_id is not a plan of yours.
  • 422 AMBIGUOUS_PLANThe plan id exists on several of your products; send product_id too.
  • 422 UNKNOWN_PRODUCTproduct_id is not a product of yours.
  • 422 OCCURRED_AT_IN_FUTUREoccurred_at is more than 5 minutes ahead.
  • 422 FX_RATE_MISSINGForeign currency without fx_rate and 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_idstringRequired

    Unique id of this event, 1–200 characters. Resending the same event with the same id is safe (idempotency).

  • external_refund_idstringRequired

    Your refund id. Unique per vendor: a resent refund is never applied twice.

  • external_transaction_idstringRequired

    The payment being refunded (as sent to /conversions).

  • amountintegerRequired

    Refunded amount, greater than 0. Integer, in minor units (paise for INR; cents for other currencies).

  • currencyone of INR | USD | EUR | GBP | AED | SGD | AUD | CADoptional

    Defaults 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.

  • reasonstringoptional

    Up to 500 characters.

  • occurred_atdatetimeRequired

    ISO 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 202 and retried automatically (see Idempotency & retries).
Request · /refunds
{
  "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"
}
Response · 200
{
  "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 this external_refund_id was already applied.

Errors

  • 400 VALIDATION_FAILEDThe body does not match the schema (error.details.issues lists 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_REUSEDevent_id was 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_idstringRequired

    Unique id of this event, 1–200 characters. Resending the same event with the same id is safe (idempotency).

  • external_referencestringRequired

    Your chargeback/dispute id. Once it is WON or LOST, later updates are ignored.

  • external_transaction_idstringRequired

    The disputed payment.

  • amountintegerRequired

    Disputed amount, greater than 0. Integer, in minor units (paise for INR; cents for other currencies).

  • currencyone of INR | USD | EUR | GBP | AED | SGD | AUD | CADoptional

    Defaults 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 | LOSTRequired

    Current state of the chargeback.

  • occurred_atdatetimeRequired

    ISO 8601 date-time with a time-zone offset, e.g. 2026-09-01T10:00:00+05:30.

Request · /chargebacks
{
  "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"
}
Response · 200
{
  "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.issues lists 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_REUSEDevent_id was 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_idstringRequired

    Unique id of this event, 1–200 characters. Resending the same event with the same id is safe (idempotency).

  • typeone of CANCELLED | REACTIVATED | PAST_DUERequired

    What happened. What a reactivation earns follows the program’s reactivation policy.

  • external_subscription_idstringRequired

    The subscription, as sent with its payments.

  • occurred_atdatetimeRequired

    ISO 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 202 and retried.
Request · /subscriptions/events
{
  "event_id": "evt_126",
  "type": "CANCELLED",
  "external_subscription_id": "sub_123",
  "occurred_at": "2026-10-01T00:00:00+05:30"
}
Response · 200
{
  "success": true,
  "data": {
    "event_id": "evt_126",
    "status": "PROCESSED",
    "result": {
      "subscription_id": "5d0c…",
      "status": "CANCELLED"
    }
  }
}

Result fields

subscription_id
Our id for the subscription.
status
CANCELLED, REACTIVATED or PAST_DUE.
ignored
stale_event when a newer change was already applied.

Errors

  • 400 VALIDATION_FAILEDThe body does not match the schema (error.details.issues lists 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_REUSEDevent_id was 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_idstringRequired

    Unique id of this event, 1–200 characters. Resending the same event with the same id is safe (idempotency).

  • customerobjectRequired

    The company.

  • customer.external_customer_idstringRequired

    Your customer id, 1–200 characters. Matches later payments and renewals to the same customer.

  • customer.organization_namestringRequired

    Company name, 1–200 characters. Used for deal-registration matching.

  • customer.domainstringoptional

    Company website domain, up to 253 characters. Taken from email when omitted.

  • customer.gstinstringoptional

    GSTIN, up to 15 characters. Stored only as a keyed hash.

  • customer.emailemailoptional

    Billing contact email. Stored only as a keyed hash (plus its domain).

  • customer.phonestringoptional

    Up to 20 characters. Stored only as a keyed hash.

Request · /customers
{
  "event_id": "evt_127",
  "customer": {
    "external_customer_id": "cus_1",
    "organization_name": "Acme Pvt Ltd",
    "domain": "acme.in",
    "gstin": "27AAPFU0939F1ZV"
  }
}
Response · 200
{
  "success": true,
  "data": {
    "event_id": "evt_127",
    "status": "PROCESSED",
    "result": {
      "customer_id": "7f1b…",
      "created": true
    }
  }
}

Result fields

customer_id
Our id for the customer.
created
true for a new customer, false for an update.

Errors

  • 400 VALIDATION_FAILEDThe body does not match the schema (error.details.issues lists 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_REUSEDevent_id was 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_idstringRequired

    Unique id of this event, 1–200 characters. Resending the same event with the same id is safe (idempotency).

  • partner_codestringRequired

    The partner’s referral code, up to 60 characters.

  • product_iduuidRequired

    Our product id.

  • company_namestringRequired

    2–160 characters.

  • contact_namestringRequired

    1–120 characters.

  • contact_emailemailRequired

    Lead contact email.

Request · /leads
{
  "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]"
}
Response · 200
{
  "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.issues lists 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_REUSEDevent_id was 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_idstringRequired

    Unique id of this event, 1–200 characters. Resending the same event with the same id is safe (idempotency).

  • typeone of lead.stage_changedRequired

    Always lead.stage_changed.

  • spm_iduuidoptional

    Our lead id (from our CRM webhook). Either spm_id or external_id is required.

  • external_idstringoptional

    Your CRM record id, once your receiver returned it to us. Either this or spm_id is required.

  • stagestringRequired

    Your CRM stage name, 1–100 characters.

  • occurred_atdatetimeRequired

    ISO 8601 date-time with a time-zone offset, e.g. 2026-09-01T10:00:00+05:30.

Request · /crm/events
{
  "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"
}
Response · 200
{
  "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.
unchanged
true when the lead already had that status.
ignored
unmapped_stage or invalid_transition; the event is acknowledged and nothing changes.

Errors

  • 400 VALIDATION_FAILEDThe body does not match the schema (error.details.issues lists 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_REUSEDevent_id was 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_preview shows the amount, the calculation base, the rule and the hold that would apply, and result.attribution_preview the partner that would be credited.
  • Test events are idempotent separately from live ones: the same event_id can 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.
Test-mode response · 200
{
  "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 as external_id in 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.
Webhook body · LEAD_CREATED
{
  "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.

  1. 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.

  2. Upgrades and click stitching

    event_type: EXPANSION for subscription upgrades, and attribution.visitor_id for programs that stitch several clicks of one visitor.

  3. CRM sync

    POST /crm/events and signed outbound CRM webhooks for leads and deals.

Questions about an integration? Contact us or open a support ticket from the vendor portal.