Skip to content
HeadlessWP Pro

Affiliate track

id: core-affiliate-track owner: core method: POST path: /wp-json/headlesswp/v1/affiliate/track title: Affiliate track usedBySite: true

POST /wp-json/headlesswp/v1/affiliate/track

Sets AffiliateWP-compatible tracking cookies from the headless client and records an AffiliateWP visit when AffiliateWP is active.

Auth + CSRF

  • Auth: public
  • Proxy nonce required: yes (via /api/secure/**)
  • CSRF: proxy-enforced X-WP-Nonce for POST requests.

Request schema

JSON body fields:

  • ref (required, string | int): affiliate ID. Must resolve to a positive integer after normalization.
  • campaign (optional, string): campaign slug up to 128 characters. Empty/whitespace-only strings are treated as not provided.
  • landingUrl (optional, string | null): absolute http(s) URL for the landing page.
  • referrer (optional, string | null): absolute http(s) URL for document referrer.

Notes:

  • Unknown fields are rejected with VALIDATION_FAILED and fieldErrors.
  • ref is normalized by stripping non-digits and leading zeros before validation.

Response schema

Success envelope:

{
  "data": {
    "ref": "123",
    "campaign": null,
    "ttlSeconds": 2592000,
    "expiresAt": "2026-01-03T07:48:01+00:00",
    "flags": {
      "domain": "",
      "path": "/",
      "secure": true,
      "httpOnly": true,
      "sameSite": "Lax"
    }
  },
  "meta": {
    "correlationId": "abc123",
    "visitRecorded": true,
    "visitId": 987
  }
}
  • campaign is null when not provided.
  • ttlSeconds reflects the resolved cookie TTL (AffiliateWP settings or fallback).
  • flags echo the configured cookie attributes.
  • meta.visitRecorded is true when an AffiliateWP visit row was created.
  • meta.visitId is the created visit ID, otherwise null.
  • Cookies emitted by this route include affwp_ref, optional affwp_campaign, and affwp_ref_visit_id (visit-link cookie used by AffiliateWP to attach checkout referrals back to the originating visit so conversion state flips from false to true).

Error codes

  • UNSUPPORTED_MEDIA_TYPE (415) — Content-Type must be application/json.
  • VALIDATION_FAILED (422) — validation failed (see fieldErrors).
  • RATE_LIMITED (429) — rate limit exceeded (details.bucket = "affiliate_track").