Skip to content

docs(impact): add affiliate tracking spec and implementation plan#1761

Draft
jeanduplessis wants to merge 1 commit intomainfrom
impact-tracking
Draft

docs(impact): add affiliate tracking spec and implementation plan#1761
jeanduplessis wants to merge 1 commit intomainfrom
impact-tracking

Conversation

@jeanduplessis
Copy link
Copy Markdown
Contributor

Summary

Adds the spec and implementation plan for Impact.com affiliate tracking integration for KiloClaw subscriptions. This replaces the existing Rewardful integration.

  • .specs/impact-affiliate-tracking.md — Business rules spec defining attribution semantics, conversion events (SIGNUP, TRIAL_START, TRIAL_END, SUBSCRIPTION_START), reliability requirements, and GDPR handling.
  • plans/impact-affiliate-tracking.md — Implementation plan covering Rewardful removal, user_affiliate_attributions table, Impact.com API client, UTT installation, click ID capture through OAuth flow, and server-side conversion tracking in Stripe webhook handlers.

No code changes — docs only. Implementation will follow in subsequent PRs.

Verification

  • Formatting passes (oxfmt)
  • No code changes, so typecheck/lint/tests are unaffected

Visual Changes

N/A

Reviewer Notes

The spec and plan were developed based on Impact.com's integration docs and the technical recommendations from their Solutions Architect (Pierluigi Stasi). Key architectural decisions:

  • user_affiliate_attributions table rather than a column on kilocode_users, to support multiple affiliate providers over time.
  • AffiliateProvider enum with enumCheck constraint, following existing schema patterns.
  • First-touch attribution enforced by a unique constraint on (user_id, provider).
  • Hybrid tracking: UTT for cross-domain identity bridging + server-side Conversions API for reliable event reporting.

Open items that require Impact.com account setup are listed at the end of the plan.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant