Run an Affiliate Program

Stand up a partner program for your own product end to end — enroll affiliates as orgs, attribute conversions, and keep an accurate commission ledger you settle with your affiliates — 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.

You pay your affiliates. Program management, enrollment, attribution, commission accrual, clawback, analytics, and notifications are live. Amba keeps the commission ledger; it does not send money for your program. Settle each affiliate's payable commission yourself, using the ledger (amba_affiliate_conversions_list, amba_affiliate_analytics_get) as the record. amba_affiliate_payout_run on your program returns 409 PAYOUT_FUNDING_UNAVAILABLE.

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; it takes an optional invite_code, see Getting access), 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. Settle with your affiliates

Amba sends payouts only for programs it funds itself (its own partner program), and only on conversions a payment provider confirmed. Conversions you report through the API are your own records, so Amba keeps them in the ledger and never pays them out. For your program:

Read what each affiliate has earned with amba_affiliate_analytics_get and amba_affiliate_conversions_list, and pay them through your own payout process.
amba_affiliate_payout_run { program_id } returns 409 PAYOUT_FUNDING_UNAVAILABLE for your program, and the weekly/monthly schedule skips it; the commissions stay in the ledger.
amba_affiliate_my_payout_request lets an affiliate see exactly what they're owed.