X-Api-Key. A key created for a team member only sees what that member’s permissions allow.
Things to know before you call:
- Tracking references differ per operation.
customers.createneeds one of coupon, click ID, referral code, asset ID or tracking ID, andsource_idonly goes withasset_id.conversions.createtakes the same references, orcustomer_idalone when it matches an existing customer in a recurring program (Tapfiliate answers 400 otherwise).clicks.createnames the affiliate withreferral_code(asource_idbeside it overrides the code’s source) or withasset_idplussource_id; a coupon, click ID or tracking ID doesn’t identify a click. The plugin checks these before sending. - Ranking when several are sent. Tapfiliate uses only the highest-precedence reference: coupon, then click ID, then referral code, then asset ID with source ID, then tracking ID.
- A conversion creates commissions.
conversions.createcreates the regular commission and any MLM level commissions. If you passcommissions, theirsub_amounts must add up toamount, and you get one commission per entry instead of the program’s default. - Converting an amount does not move the commission.
conversions.updatechangesamountonly. Commission amounts change when the call also sendsrecalculate_commissions: true, which travels as a query flag. - Creating an affiliate may answer no body. The reference documents a 200 with no body, so
affiliates.createthen reports{ created: true, email }and the id comes fromaffiliates.list. When Tapfiliate does return the affiliate with a generatedpassword, store it: it is the only way into the new account. - An incomplete address is dropped silently. Tapfiliate keeps an address only when
address,postal_code,cityandcountry.codeare all present. The plugin requires them together. - Approval defaults to yes.
programs.addAffiliateapproves unless you sendapproved: falsefor disapproved orapproved: nullfor pending, and it ignores the program’s auto-approve setting. - Coupon updates are three-way. In
programs.updateAffiliate,coupon: nullremoves the coupon, a string replaces it, and leaving the field out changes nothing. - Deletes. A 204 answers with no body, so the delete endpoints report
{ success: true }.payments.cancelis a DELETE route that cancels the payment (the affiliate balance goes back up by its amount, and there is no undo).customers.cancelstops recurring commissions andcustomers.uncancelrestores them. - Paging is by page number. Lists return 25 items per page and put the next page in the
Linkheader, which the plugin cannot read with the body, so passpageyourself and keep requesting until a page comes back short. - Rate limits and plans. Limits range from 10 to 1500 requests per window per key and endpoint. A 429 carries no
Retry-After; the plugin retries three times with backoff. Click routes need the click-report feature, and affiliate groups need a plan that includes them, or they answer 403.
- 41 typed API operations
Setup
1
Install
2
Add the plugin
corsair.ts
multiTenancy: true, scope calls with corsair.withTenant(id). See Quick start for KEK + Hub keys, and Multi-tenancy for account isolation.3
Choose authentication
- API Key (Recommended)
Store the Tapfiliate API key before the first call: More: API Key
pnpm corsair setup --plugin=tapfiliate --tenant=acme api_key=<your-key> (leave out --tenant without multiTenancy), or pass it as key in the plugin options. With Hub, each tenant enters their own key on the connect page. See API key auth.4
Connect a tenant
Mint a connect link and send the tenant to it. Hub hosts the page and delivers the result to your app — see Connect / OAuth.
Example API calls
List the first page of affiliatesWhat’s next
API reference
Every
tapfiliate.api.* operation with input and output types.Connect / OAuth
createLink, Hub delivery, and tenant connect flows.
Use with agents
Expose this plugin’s operations as MCP tools.