Partner Attribution

Partner attribution keeps AWIN/CJ traffic evidence separate from authoritative order finance. Use the browser SDK for ordinary touch capture. Use the server endpoint when a trusted commerce backend owns purchase, refund, correction, and cancellation truth.

Capture partner touches

POST /api/v1/partner-attribution/touches accepts 1–20 canonical touches, further limited by the site configuration. Browser requests authenticate with an origin-bound runtime bearer token. During unload, the SDK may include runtime_token in the JSON body because the beacon API cannot set headers; that exception is accepted only on whitelisted ingestion routes.

{
  "touches": [
    {
      "schema_version": 1,
      "touch_id": "touch_awin_1",
      "provider": "awin",
      "direction": "inbound",
      "provider_click_id": "3661_1358445475_f396d719f0b67247f126a90bd2898cf0",
      "partner_id": "45628",
      "landing_path": "/summer-sale",
      "occurred_at": "2026-07-12T12:30:00Z",
      "provenance": "browser_sdk"
    }
  ]
}

A new touch returns 201. An unchanged replay returns 200; reusing a touch ID with different content returns 409. Raw awc and cjevent values are encrypted before persistence and never returned by this endpoint.

Ingest trusted conversions

POST /api/v1/partner-attribution/conversions requires a secret key with partner_attribution:convert. The request has one of three envelopes:

• { "event_type": "purchase", "conversion": { ... } }
• { "event_type": "adjustment", "adjustment": { ... } }
• { "event_type": "cancellation", "cancellation": { ... } }

{
  "event_type": "purchase",
  "conversion": {
    "schema_version": 1,
    "idempotency_key": "wc:website-1:order-1001",
    "website_id": "website-1",
    "order_id": "1001",
    "occurred_at": "2026-07-12T13:00:00Z",
    "currency": "EUR",
    "revenue": 129.99,
    "commissionable_subtotal": 120,
    "tax": 9.99,
    "shipping": 0,
    "discount": 0,
    "lines": [
      {
        "line_id": "line-1",
        "sku": "SHOE-1",
        "quantity": 1,
        "unit_price": 120,
        "subtotal": 120,
        "discount": 0,
        "commissionable_amount": 120,
        "item_cost": 68.5
      }
    ],
    "margin": { "amount": 51.5, "basis": "exact", "source": "order_costs" },
    "touch_ids": ["touch_awin_1"],
    "experiment_assignment_ids": ["peasg_abc123"]
  }
}

Order totals must reconcile with line values. Exact costs must cover every line, and exact margin must reconcile with net merchandise revenue. Adjustments require an earlier purchase in the same site and currency, cannot make revenue negative, and must advance the source timestamp. Cancellation must reverse the full remaining revenue and is terminal.

The first accepted request returns 201 and authoritative: true. Replaying the same idempotency key and payload returns the same IDs with 200 and deduplicated: true. A changed replay returns 409.

Observational browser purchases

A browser purchase sent to event tracking remains an analytics observation. It never replaces the trusted conversion record used for reconciliation.

Partner experience experiments

Authenticated merchants manage experiments through /partner-experiments and read /partner-experiments/{experimentId}/results. The browser SDK uses its runtime capability at /partner-experiments/assignments to receive a stable control or treatment assignment before selected overlay, recommendation, or chatbot campaigns load.

Results use eligible sessions as the intent-to-treat denominator and report conversion, revenue/session, gross profit/session, and partner contribution/session with sample-ratio, power, late-conversion, refund, and cancellation states. They measure selected Upsurge experiences within eligible partner traffic; they do not claim a partner's total incrementality.

Publisher mode

Publisher mode decorates allowlisted AWIN links with clickref and CJ links with sid. Automatic decoration is opt-in and only applies to explicitly marked links. Content, campaign, placement, creative, and destination context are captured separately from provider click IDs.

Mark automatic links with data-upsurge-partner-provider and data-upsurge-click-reference; optional taxonomy attributes are data-upsurge-partner-id, data-upsurge-campaign-id, data-upsurge-content-id, data-upsurge-placement-id, and data-upsurge-creative-id.

GET /analytics/publishers requires an authenticated owner and an active publisher-mode website. It returns Upsurge-observed clicks alongside provider-settled orders, commissionable revenue, approved/pending/declined commission, reversals, top content/destinations, and reference-correlation variance. Raw click references do not enter analytics facts.