Affiliate tracking

What affiliate tracking does, the three pattern types and validation rules, default seeds, detection priority, and the URL tester.

What affiliate tracking does#

Affiliate tracking identifies affiliate links among on-site clicks and aggregates clicks by affiliate program and affiliate ID. It is merged into the conversion tracking page /dashboard/mkit/conversions; /dashboard/mkit/forms-aff only redirects. Report data comes from the affiliate field of GET /api/v1/reports/forms-aff.

Endpoint	Purpose
GET /api/v1/sites/:siteId/aff-patterns	List detection rules; the first visit seeds the defaults
POST /api/v1/sites/:siteId/aff-patterns	Create a rule
POST /api/v1/sites/:siteId/aff-patterns/test	Test detection with a single URL
PATCH /api/v1/sites/:siteId/aff-patterns/:patternId	Update a rule
DELETE /api/v1/sites/:siteId/aff-patterns/:patternId	Delete a rule

Note: The report is locked on Free. GET (list) returns { locked: true, plan, patterns: [] } on Free; POST (create) throws ValidationError("AFF patterns are a Pro feature") on Free; PATCH, DELETE and POST test have no explicit plan check.

Three pattern types and validation#

AffiliatePattern fields include id, site_id, pattern_type, pattern, program, program_custom, commission_rate, id_extraction, is_active and created_at.

Type	Validation	Matching
path	Must start and end with /, e.g. /go/; length ≤ 200	Path prefix match; if segment_1 is a known program name, program=segment_1 and id=segment_2, otherwise id=segment_1
subdomain	Must be a label matching ^[a-z0-9-]+\.?$, e.g. aff.; length ≤ 200	Matches only when host equals sub.siteDomain or ends with it
param	Must be a query parameter name matching ^[a-z][a-z0-9_]*$, e.g. tag; length ≤ 200	Matches when the query parameter exists

program must be amazon | shareasale | cj | impact | partnerstack | generic | personal | review_site | custom
program=custom requires program_custom
commission_rate must be between 0 and 100
id_extraction must be segment_1 | subdomain_only | param_value | none
pattern_type must be path | subdomain | param
The create form UI only supports adding path rules; subdomain and param rules currently require calling the API directly

Default rules seeded on first use#

On the first GET /sites/:siteId/aff-patterns, when the site has no patterns and the plan is Pro or Business, six default rules are seeded.

Type	pattern	program	id_extraction
path	/aff/	generic	segment_1
path	/go/	generic	segment_1
path	/recommend/	generic	segment_1
param	tag	amazon	param_value
param	aff	generic	param_value
param	ref	generic	param_value

Note: If the user deletes all six rules, the next GET seeds them again: any site with no patterns triggers the default insert.

Detection priority#

User-configured path rules
User-configured subdomain rules
User-configured param rules
Built-in parameter table: tag→amazon, afftrack→shareasale, pid→cj, clickid→impact, via→partnerstack, ref/aff/affiliate→generic
Built-in path table: /(aff|go|ref|recommend|out|promo)/...

Note: Only rules with is_active=true participate in detection; the tester reuses the same priority and enabled state.

URL tester and report metrics#

POST /api/v1/sites/:siteId/aff-patterns/test accepts a body of {"url": "https://..."} and returns url, is_affiliate, detection_type, program, affiliate_id and matched_pattern.

total_clicks: the sum of clicks across all recognized affiliate programs
programs: aggregated by program with program, type, clicks and conv_rate; conv_rate = clicks / sessions
top_ids: the top 5 affiliate IDs with id, domain and clicks
detection: clicks accumulated per detection type with path, param and subdomain

Note: When the UI test request fails it is silently ignored with no error message; the test reflects currently enabled rules only and never changes report data.

Conversion tracking report: /conversions
Ecommerce attribution report: /ecommerce-report
Data latency & metric definitions: /data-latency
Keywords report: /keywords