An affiliate program is a small revenue-share ledger that grows teeth fast: a commission model that has to handle percentage, flat, recurring, and tiered payouts; attribution that survives the gap between a click and a purchase days later; a refund window so a charged-back sale does not pay out; and partner-scoped access so one affiliate can never read another’s numbers. Amba ships this as a feature of the backend you already have. Affiliates enroll as Amba orgs, each with their own PAT — two accounts, two token scopes, zero dashboards — and the admin (`amba_affiliate_*`) and self-service (`amba_affiliate_my_*`) tool families are structurally scoped, so a `_my_` tool takes no other-affiliate id and a partner cannot reach a peer. Program management, enrollment, attribution (a reported code or an in-app affiliate-link click), commission accrual, refund clawback, analytics, and partner notifications are LIVE. The money-out transfer is in preview: `amba_affiliate_payout_run` and the scheduled settlement ship GATED OFF behind the operator flag `ORG_PAYOUTS_LIVE` and return 503 `PAYOUTS_NOT_ENABLED` until it is enabled — so this is not same-day affiliate cash-out today, it is the full accrual and program engine with the transfer rail behind a flag.
How does affiliate commission get modeled?
Commission is a versioned JSONB tagged union, so one program can pay any common shape: {"type":"percentage","bps":2000} for 20% of the sale, {"type":"flat","amount_cents":5000} for a fixed $50, {"type":"recurring","bps":2000,"max_cycles":12} to pay on each renewal up to a cap, or {"type":"tiered","bps":1000,"tiers":[{"min_conversions":10,"bps":2000}]} to raise the rate once an affiliate clears a volume threshold. An optional "multi_level":[{"level":1,"bps":500}] ladder pays upline overrides, but it is DOUBLE-gated — per-program multi_level_enabled AND a platform ORG_MULTI_LEVEL_LIVE server flag — because MLM-shaped payouts carry real regulatory exposure. platform_fee_bps is the owner’s cut deducted from each payout; funding_source records the intended source — split_at_source (default — the sale ran through Amba Payments) or external — but since money-out is in preview, it is recorded rather than yet enforcing pass-through settlement.
How are conversions attributed to an affiliate?
A program declares what counts (conversion_kind of event, payment, or entitlement) and how credit is assigned (attribution_model of first_touch or last_touch, within attribution_window_days, default 30). Attribution happens two ways. (a) The conversion is reported with an explicit affiliate code. (b) A visitor clicks an in-app affiliate link, which records a tenant-side touchpoint via the client endpoint below; on conversion, a report with no code PROMOTES the latest touchpoint inside the window to the control-plane ledger. Recorded clicks are what make EPC and conversion-rate real in analytics — without them you have commission totals but no funnel. Conversions are idempotent on (program_id, project_id, external_id), so a retried server-to-server report never double-credits.
What happens when a sale is refunded?
A hold_period_days refund window holds commission back before it becomes payable, and amba_affiliate_conversion_clawback handles a refund or chargeback after the fact: a pre-payout commission is simply reversed, and an already-PAID commission becomes a negative carry-forward netted against the affiliate’s next payout — the program never has to chase a partner for money back. On the upside, notifications are automatic: when a commission is approved or paid, the affiliate org owner is emailed (best-effort), so partners learn they earned without you wiring a comms pipeline.
How do affiliates see their own numbers without a dashboard?
Each affiliate is an Amba org with its own PAT, and the self-service tool family is the affiliate’s entire surface: amba_affiliate_my_programs_list and _invites_list to see programs, _invite_accept to join, _referral_get / _referral_generate for their codes and links, _stats_get and _conversions_list for performance, _balance_get for what they are owed, and _payouts_list with the payout-request and onboarding tools for getting paid. Because a _my_ tool derives the affiliate from the caller’s own org and takes no other-affiliate id, the isolation is structural — there is no query an affiliate can phrase that reads a peer. An AI agent on the affiliate side can self-serve the whole loop.
An optional "multi_level":[{"level":1,"bps":500}] ladder pays upline overrides — DOUBLE-gated behind per-program multi_level_enabled AND the platform ORG_MULTI_LEVEL_LIVE flag. Models verified against the live tool registry, June 2026.
How does an AI agent stand up an affiliate program?
Program → launch → enroll → analytics — real tools, schema-true arguments
Tool names and argument shapes are from the live tool registry, June 2026. Money-out (amba_affiliate_payout_run) is gated behind ORG_PAYOUTS_LIVE and returns 503 PAYOUTS_NOT_ENABLED until enabled.
How does the app record an affiliate-link click?
Record an in-app touchpoint — works pre-auth, no SDK method required
Endpoint, headers, and body verified against the client route source (apps/api/src/routes/client/affiliate.ts), June 2026. The session is optional, so the click can be recorded before the visitor has an app_user.
Which MCP tools cover this surface?
When is this not the right call?
- Money-out (payout transfer) is in preview, gated off
- Program management, enrollment, attribution, commission accrual, clawback, analytics, and notifications are live — but the actual transfer (amba_affiliate_payout_run and the scheduled settlement) ships gated behind the ORG_PAYOUTS_LIVE operator flag and returns 503 PAYOUTS_NOT_ENABLED until enabled. As of mid-2026 this is the full accrual engine; same-day affiliate cash-out is not live yet.
- Multi-level (upline override) payouts are double-gated
- The optional multi_level ladder that pays sponsors on a downline’s sales is gated behind both per-program multi_level_enabled and a platform ORG_MULTI_LEVEL_LIVE flag, because MLM-shaped payouts carry regulatory exposure we will not flip on by default. If your model is a flat single-tier revenue share, you never touch this; if you need an MLM ladder live, that is a deliberate operator decision, not a self-serve toggle.
- A pure web influencer network may want a dedicated affiliate platform
- Amba’s affiliate engine is built for in-app attribution — the touchpoint click and the conversion both originate in your mobile app. If you are running a web-only influencer network with coupon-site partners, link cloaking, and creative asset hosting, a purpose-built affiliate SaaS as of mid-2026 has surface area Amba does not claim.
Can an AI agent set this up end to end?
Yes. Amba’s hosted MCP server at https://mcp.amba.dev/mcp (Streamable HTTP) exposes the whole backend as tool calls. amba_developer_signup mints a developer token and a provisioned project — client key and server key included — with no browser, and the project goes active in about ten seconds. The whole program above — create with a commission model, launch it active, invite a partner, read analytics — is four tool calls after signup, and the affiliate side self-serves entirely through the amba_affiliate_my_* family; your agent can stand up both sides of a referral economy without a dashboard.
Affiliate API — FAQ
What is an affiliate program API?
A backend service that runs a referral-marketing program as configurable rules instead of code you write. You define a commission model and what counts as a conversion; the service enrolls affiliates, attributes conversions to whoever drove them, accrues commission with a refund holdback, handles clawbacks, and reports analytics — so partners earn on the sales they bring without you building the ledger.
How does Amba attribute an affiliate conversion?
Two ways. Either the conversion is reported with an explicit affiliate code, or a visitor clicks an in-app affiliate link that records a touchpoint; a report with no code then credits the latest touchpoint within the attribution window (first_touch or last_touch, default 30 days). Conversions are idempotent on the external id, so a retried server-to-server report never double-credits an affiliate.
Can affiliates be paid out automatically?
Not yet. As of mid-2026 the money-out transfer is in preview: amba_affiliate_payout_run and the scheduled settlement are gated behind the ORG_PAYOUTS_LIVE operator flag and return 503 PAYOUTS_NOT_ENABLED until enabled. Everything up to payout — program management, attribution, commission accrual, refund clawback, analytics, and partner notifications — is live, so balances are tracked even before transfers turn on.
How is one affiliate stopped from seeing another’s data?
Structurally. Each affiliate enrolls as its own Amba org with its own PAT, and the self-service tools (amba_affiliate_my_*) derive the affiliate from the caller’s org and take no other-affiliate id. There is no query an affiliate can phrase that reads a peer — the admin tools (amba_affiliate_*) are a separate family scoped to the program owner.
What commission models are supported?
Four, as a versioned tagged union: percentage (a share of the sale), flat (a fixed amount per conversion), recurring (a share on each renewal up to max_cycles), and tiered (a base rate that steps up past a volume threshold). An optional multi-level upline ladder also exists but is double-gated behind a per-program flag and a platform flag for regulatory reasons.
Is there an affiliate SDK method for the client app?
No — the only client-facing affiliate surface is one REST endpoint, POST /v1/client/affiliate/touchpoint, which records an affiliate-link click and works before the visitor has signed up. Everything else (programs, enrollment, conversions, analytics, payouts) is admin or self-service MCP tools and the server-to-server conversion report; there is no Amba.affiliate.* client call.
Sources for this guide
- Amba admin API reference: affiliate as of 2026-06
- Amba economy docs: Affiliate Programs as of 2026-06