Run an Affiliate Program

Stand up a partner program for your own product end to end — enroll affiliates as orgs, attribute conversions, accrue commission, and (when enabled) pay out — all from MCP.

Affiliate Programs let your customers run a partner program for their product without a dashboard. The owner and every affiliate are Amba organizations with their own PAT; the whole flow is MCP tools. This guide walks the happy path end to end. Full surface: the Affiliate API reference.

Money-out is in preview. Program management, enrollment, attribution, commission accrual, clawback, analytics, and notifications are live. The payout transfer is gated off behind ORG_PAYOUTS_LIVE (a platform-operator flag) and returns 503 until enabled after a customer-shoes test + counsel. You can build, attribute, accrue, and dry-run the whole program today; cash actually moves once your platform flips the flag.

1. Create the program

Commission is a versioned JSONB tagged union — percentage, flat, recurring, or tiered:

amba_affiliate_programs_create
  owner_organization_id: <your org id>
  name: "Launch Partners"
  commission: { "type": "percentage", "bps": 2000 }   # 20% of gross
  conversion_kind: "payment"                            # event | payment | entitlement
  attribution_model: "last_touch"                       # first_touch | last_touch
  attribution_window_days: 30
  approval_mode: "auto"                                 # auto-approve, or "manual" to review
  hold_period_days: 30                                  # refund-window holdback before payable
  platform_fee_bps: 0                                   # your cut on each payout

Then launch it: amba_affiliate_programs_update { program_id, status: "active" }.

2. Enroll affiliates

An affiliate is just an org. Two paths:

They're already on Amba: amba_affiliate_invite { program_id, affiliate_org_id } → returns their referral code. Approve a pending enrollment with amba_affiliate_affiliate_approve, or let them self-accept (below).
They're brand new: they run the public amba_affiliate_signup (one browserless call → account + org + PAT + mcp_config), then share their org id with you to enroll. From the affiliate side, amba_affiliate_my_invites_list + amba_affiliate_my_invite_accept activates the enrollment and returns their code; amba_affiliate_my_referral_generate rotates to a fresh one.

For multi-level programs, pass parent_enrollment_id to place an affiliate under a sponsor; upline overrides accrue only when the program and the platform have multi-level enabled.

3. Attribute conversions

Two ways to attribute, and you can use both:

Code (server-to-server): report the conversion from your backend with the affiliate's code.
POST /v1/admin/affiliate/programs/:programId/conversions { "project_id": "...", "external_id": "order_123", "code": "aff_ab12cd", "gross_amount_cents": 9900 }
Reports are idempotent on (program_id, project_id, external_id).
In-app link (touchpoint): when a visitor lands via an affiliate link, record a touchpoint from the app — no session required, so a pre-auth click counts:
POST /v1/client/affiliate/touchpoint (X-Api-Key) { "code": "aff_ab12cd", "source": "link", "anonymous_id": "anon_9f3" }
Later report the conversion without a code (pass the same subject as subject_ref); Amba promotes the latest touchpoint within the attribution window to the ledger. Recorded clicks are what make EPC and conversion-rate real in analytics.

A manual-approval program books conversions as pending — approve them with amba_affiliate_conversion_approve (or _reject). Approval is when commission accrues, and the affiliate is emailed automatically.

4. Watch it perform

amba_affiliate_analytics_get { program_id } — totals, clicks, EPC, conversion-rate, and a leaderboard.
amba_affiliate_leaderboard_get — standalone top-affiliates view.
Affiliates read their own side with amba_affiliate_my_stats_get / _balance_get / _conversions_list — structurally scoped, so they can never see a peer.

5. Handle refunds (clawback)

If a sale refunds or charges back, claw the conversion back:

POST /v1/admin/affiliate/programs/:programId/conversions/:conversionId/clawback
{ "reason": "refund" }

Pre-payout commissions are reversed outright. An already-paid commission becomes negative carry-forward — it nets against the affiliate's next payout rather than demanding the cash back. (A transfer.reversed Connect event does the same automatically for a settled transfer.)

6. Pay out (when enabled)

Each affiliate sets up a payout account once (amba_affiliate_my_payout_create → amba_affiliate_my_payout_onboarding → finish the hosted Stripe onboarding). Then:

On demand: amba_affiliate_payout_run { program_id } pays each affiliate their payable commission over the threshold, net of platform_fee_bps and any carry-forward debt.
On a schedule: set payout_schedule: "weekly" | "monthly" and a scheduled settlement runs it unattended.

While ORG_PAYOUTS_LIVE is off, both paths return 503 PAYOUTS_NOT_ENABLED — that's the preview gate, not a bug. amba_affiliate_my_payout_request lets an affiliate see exactly what they're owed and confirm their account is ready in the meantime.