Can I use Tapfiliate as a CLI?

Yes. KosmoKrator exposes a Tapfiliate CLI through kosmo integrations:call and the provider shortcut command. Commands can return JSON for scripts, CI, and coding agents.

Can I expose Tapfiliate through MCP?

Yes. The KosmoKrator MCP gateway can expose selected Tapfiliate tools to clients such as Claude Code, Cursor, Codex, and other MCP-compatible tools.

Where are Tapfiliate credentials stored?

Tapfiliate credentials are configured in KosmoKrator's local integration settings and reused by CLI, Lua, and MCP gateway surfaces.

Can I deny write access for Tapfiliate MCP tools?

Yes. Start the gateway with --write=deny for read-only clients, or use ask/allow only for trusted workspaces.

analytics

Tapfiliate Lua API for KosmoKrator Agents

Agent-facing Lua documentation and function reference for the Tapfiliate KosmoKrator integration.

Lua Namespace

Agents call this integration through app.integrations.tapfiliate.*. Use lua_read_doc("integrations.tapfiliate") inside KosmoKrator to discover the same reference at runtime.

Call Lua from the Headless CLI

Use kosmo integrations:lua when a shell script, CI job, cron job, or another coding CLI should run a deterministic Tapfiliate workflow without starting an interactive agent session.

Inline Lua call

kosmo integrations:lua --eval 'dump(app.integrations.tapfiliate.get_current_user({}))' --json

Read Lua docs headlessly

kosmo integrations:lua --eval 'print(docs.read("tapfiliate"))' --json
kosmo integrations:lua --eval 'print(docs.read("tapfiliate.get_current_user"))' --json

Workflow file

Put repeatable logic in a Lua file, then execute it with JSON output for the calling process.

workflow.lua

local tapfiliate = app.integrations.tapfiliate
local result = tapfiliate.get_current_user({})

dump(result)

Run the workflow

kosmo integrations:lua workflow.lua --json
kosmo integrations:lua workflow.lua --force --json

Namespace note. integrations:lua exposes app.integrations.tapfiliate, app.mcp.*, docs.*, json.*, and regex.*. Use app.integrations.tapfiliate.default.* or app.integrations.tapfiliate.work.* when you configured named credential accounts.

MCP-only Lua

If the script only needs configured MCP servers and does not need Tapfiliate, use the narrower mcp:lua command.

MCP Lua command

# Use mcp:lua for MCP-only scripts; use integrations:lua for this integration namespace.
kosmo mcp:lua --eval 'dump(mcp.servers())' --json

Agent-Facing Lua Docs

This is the rendered version of the full Lua documentation exposed to agents when they inspect the integration namespace.

Tapfiliate Lua Reference

This integration targets Tapfiliate REST API v1.6 and authenticates with X-Api-Key. Use it for affiliate operations, conversion tracking, commission reconciliation, customer attribution, and program configuration lookups.

Affiliates

local affiliates = app.integrations.tapfiliate.list_affiliates({
  email = "partner@example.test",
  referral_code = "PARTNER",
  limit = 50,
  page = 1
})

local affiliate = app.integrations.tapfiliate.get_affiliate({
  id = "aff_123"
})

Create and update affiliates:

local created = app.integrations.tapfiliate.create_affiliate({
  firstname = "Ada",
  lastname = "Lovelace",
  email = "ada@example.test",
  company = { name = "Example Partners" },
  custom_fields = { channel = "newsletter" }
})

local updated = app.integrations.tapfiliate.update_affiliate({
  affiliate_id = "aff_123",
  firstname = "Ada",
  custom_fields = { tier = "gold" }
})

Group and notes tools:

app.integrations.tapfiliate.set_affiliate_group({
  affiliate_id = "aff_123",
  group_id = "group_1"
})

local notes = app.integrations.tapfiliate.list_affiliate_notes({
  affiliate_id = "aff_123"
})

local groups = app.integrations.tapfiliate.list_affiliate_groups({})

Conversions

List and retrieve conversions:

local conversions = app.integrations.tapfiliate.list_conversions({
  affiliate_id = "aff_123",
  program_id = "prog_1",
  status = "approved",
  date_from = "2026-01-01",
  date_to = "2026-01-31"
})

local conversion = app.integrations.tapfiliate.get_conversion({
  conversion_id = "12345"
})

Create conversions by known affiliate, referral code, click/tracking id, coupon, or customer id:

local conversion = app.integrations.tapfiliate.create_conversion({
  external_id = "order_1001",
  amount = 149.99,
  currency = "USD",
  referral_code = "PARTNER",
  program_id = "prog_1",
  meta_data = {
    plan = "Pro"
  }
})

Add a commission line:

local commission = app.integrations.tapfiliate.add_conversion_commission({
  conversion_id = "12345",
  conversion_sub_amount = 49.99,
  commission_type = "default",
  comment = "Expansion revenue"
})

Commissions

local commissions = app.integrations.tapfiliate.list_commissions({
  affiliate_id = "aff_123",
  status = "approved",
  date_from = "2026-01-01"
})

local commission = app.integrations.tapfiliate.get_commission({
  commission_id = "98765"
})

Customers

local customers = app.integrations.tapfiliate.list_customers({
  program_id = "prog_1",
  affiliate_id = "aff_123"
})

local customer = app.integrations.tapfiliate.create_customer({
  customer_id = "cust_1001",
  referral_code = "PARTNER",
  program_id = "prog_1",
  meta_data = {
    email = "buyer@example.test"
  }
})

Programs

local programs = app.integrations.tapfiliate.list_programs({})

local enrollment = app.integrations.tapfiliate.get_program_affiliate({
  program_id = "prog_1",
  affiliate_id = "aff_123"
})

app.integrations.tapfiliate.update_program_affiliate({
  program_id = "prog_1",
  affiliate_id = "aff_123",
  coupon = "PARTNER10"
})

local types = app.integrations.tapfiliate.list_program_commission_types({
  program_id = "prog_1"
})

Account Check

local user = app.integrations.tapfiliate.get_current_user({})

Multi-Account Usage

app.integrations.tapfiliate.list_affiliates({})
app.integrations.tapfiliate.default.list_affiliates({})
app.integrations.tapfiliate.partner.list_affiliates({})

Raw agent markdown

# Tapfiliate Lua Reference

This integration targets Tapfiliate REST API v1.6 and authenticates with `X-Api-Key`. Use it for affiliate operations, conversion tracking, commission reconciliation, customer attribution, and program configuration lookups.

## Affiliates

```lua
local affiliates = app.integrations.tapfiliate.list_affiliates({
  email = "partner@example.test",
  referral_code = "PARTNER",
  limit = 50,
  page = 1
})

local affiliate = app.integrations.tapfiliate.get_affiliate({
  id = "aff_123"
})
```

Create and update affiliates:

```lua
local created = app.integrations.tapfiliate.create_affiliate({
  firstname = "Ada",
  lastname = "Lovelace",
  email = "ada@example.test",
  company = { name = "Example Partners" },
  custom_fields = { channel = "newsletter" }
})

local updated = app.integrations.tapfiliate.update_affiliate({
  affiliate_id = "aff_123",
  firstname = "Ada",
  custom_fields = { tier = "gold" }
})
```

Group and notes tools:

```lua
app.integrations.tapfiliate.set_affiliate_group({
  affiliate_id = "aff_123",
  group_id = "group_1"
})

local notes = app.integrations.tapfiliate.list_affiliate_notes({
  affiliate_id = "aff_123"
})

local groups = app.integrations.tapfiliate.list_affiliate_groups({})
```

## Conversions

List and retrieve conversions:

```lua
local conversions = app.integrations.tapfiliate.list_conversions({
  affiliate_id = "aff_123",
  program_id = "prog_1",
  status = "approved",
  date_from = "2026-01-01",
  date_to = "2026-01-31"
})

local conversion = app.integrations.tapfiliate.get_conversion({
  conversion_id = "12345"
})
```

Create conversions by known affiliate, referral code, click/tracking id, coupon, or customer id:

```lua
local conversion = app.integrations.tapfiliate.create_conversion({
  external_id = "order_1001",
  amount = 149.99,
  currency = "USD",
  referral_code = "PARTNER",
  program_id = "prog_1",
  meta_data = {
    plan = "Pro"
  }
})
```

Add a commission line:

```lua
local commission = app.integrations.tapfiliate.add_conversion_commission({
  conversion_id = "12345",
  conversion_sub_amount = 49.99,
  commission_type = "default",
  comment = "Expansion revenue"
})
```

## Commissions

```lua
local commissions = app.integrations.tapfiliate.list_commissions({
  affiliate_id = "aff_123",
  status = "approved",
  date_from = "2026-01-01"
})

local commission = app.integrations.tapfiliate.get_commission({
  commission_id = "98765"
})
```

## Customers

```lua
local customers = app.integrations.tapfiliate.list_customers({
  program_id = "prog_1",
  affiliate_id = "aff_123"
})

local customer = app.integrations.tapfiliate.create_customer({
  customer_id = "cust_1001",
  referral_code = "PARTNER",
  program_id = "prog_1",
  meta_data = {
    email = "buyer@example.test"
  }
})
```

## Programs

```lua
local programs = app.integrations.tapfiliate.list_programs({})

local enrollment = app.integrations.tapfiliate.get_program_affiliate({
  program_id = "prog_1",
  affiliate_id = "aff_123"
})

app.integrations.tapfiliate.update_program_affiliate({
  program_id = "prog_1",
  affiliate_id = "aff_123",
  coupon = "PARTNER10"
})

local types = app.integrations.tapfiliate.list_program_commission_types({
  program_id = "prog_1"
})
```

## Account Check

```lua
local user = app.integrations.tapfiliate.get_current_user({})
```

## Multi-Account Usage

```lua
app.integrations.tapfiliate.list_affiliates({})
app.integrations.tapfiliate.default.list_affiliates({})
app.integrations.tapfiliate.partner.list_affiliates({})
```

Metadata-derived Lua example

local result = app.integrations.tapfiliate.get_current_user({})
print(result)

Functions

get_current_user Read

Get the currently authenticated Tapfiliate user profile. Useful for verifying API credentials and checking account details.

Lua path: app.integrations.tapfiliate.get_current_user
Full name: tapfiliate.tapfiliate_get_current_user

Parameter	Type	Required	Description
No parameters.

list_affiliates Read

List affiliates in your Tapfiliate account. Returns paginated results with affiliate IDs, emails, names, and status.

Lua path: app.integrations.tapfiliate.list_affiliates
Full name: tapfiliate.tapfiliate_list_affiliates

Parameter	Type	Required	Description
`limit`	integer	no	Number of affiliates per page (default: 25, max: 100).
`page`	integer	no	Page number for pagination (default: 1).
`email`	string	no	Filter by email address.
`referral_code`	string	no	Filter by affiliate referral code.
`click_id`	string	no	Filter by click id.
`source_id`	string	no	Filter by source id.
`parent_id`	string	no	Retrieve children for a parent affiliate.
`affiliate_group_id`	string	no	Filter by affiliate group id.

get_affiliate Read

Get detailed information about a specific affiliate by their ID. Includes email, name, status, and metadata.

Lua path: app.integrations.tapfiliate.get_affiliate
Full name: tapfiliate.tapfiliate_get_affiliate

Parameter	Type	Required	Description
`id`	string	yes	The affiliate ID.

create_affiliate Write

Create a Tapfiliate affiliate with profile, company, address, and custom field data.

Lua path: app.integrations.tapfiliate.create_affiliate
Full name: tapfiliate.tapfiliate_create_affiliate

Parameter	Type	Required	Description
`firstname`	string	yes	Affiliate first name.
`lastname`	string	yes	Affiliate last name.
`email`	string	yes	Affiliate email address.
`password`	string	no	Optional affiliate portal password.
`company`	object	no	Company object, for example {name: "..."}
`address`	object	no	Address object with address, postal_code, city, state, and country code.
`custom_fields`	object	no	Custom field values.

update_affiliate Write

Update a Tapfiliate affiliate profile, company, address, or custom field data.

Lua path: app.integrations.tapfiliate.update_affiliate
Full name: tapfiliate.tapfiliate_update_affiliate

Parameter	Type	Required	Description
`affiliate_id`	string	yes	Affiliate ID to update.
`firstname`	string	no	Affiliate first name.
`lastname`	string	no	Affiliate last name.
`email`	string	no	Affiliate email address.
`company`	object	no	Company object.
`address`	object	no	Address object.
`custom_fields`	object	no	Custom field values.

delete_affiliate Write

Delete a Tapfiliate affiliate by ID.

Lua path: app.integrations.tapfiliate.delete_affiliate
Full name: tapfiliate.tapfiliate_delete_affiliate

Parameter	Type	Required	Description
`affiliate_id`	string	yes	Affiliate ID to delete.

set_affiliate_group Write

Assign an affiliate to a Tapfiliate affiliate group.

Lua path: app.integrations.tapfiliate.set_affiliate_group
Full name: tapfiliate.tapfiliate_set_affiliate_group

Parameter	Type	Required	Description
`affiliate_id`	string	yes	Affiliate ID.
`group_id`	string	yes	Affiliate group ID.

list_affiliate_notes Read

List notes attached to a Tapfiliate affiliate.

Lua path: app.integrations.tapfiliate.list_affiliate_notes
Full name: tapfiliate.tapfiliate_list_affiliate_notes

Parameter	Type	Required	Description
`affiliate_id`	string	yes	Affiliate ID.

list_affiliate_groups Read

List all Tapfiliate affiliate groups.

Lua path: app.integrations.tapfiliate.list_affiliate_groups
Full name: tapfiliate.tapfiliate_list_affiliate_groups

Parameter	Type	Required	Description
No parameters.

list_conversions Read

List conversions in your Tapfiliate account. Supports filtering by affiliate, campaign, date range, and status. Results are paginated.

Lua path: app.integrations.tapfiliate.list_conversions
Full name: tapfiliate.tapfiliate_list_conversions

Parameter	Type	Required	Description
`affiliate_id`	string	no	Filter by affiliate ID.
`program_id`	string	no	Filter by program ID.
`external_id`	string	no	Filter by external ID (e.g., order or transaction ID).
`status`	string	no	Filter by status: "approved", "pending", or "rejected".
`date_from`	string	no	Start date filter (ISO 8601, e.g., "2025-01-01").
`date_to`	string	no	End date filter (ISO 8601, e.g., "2025-12-31").
`limit`	integer	no	Number of results per page (default: 25, max: 100).
`page`	integer	no	Page number for pagination (default: 1).

get_conversion Read

Get a Tapfiliate conversion by ID.

Lua path: app.integrations.tapfiliate.get_conversion
Full name: tapfiliate.tapfiliate_get_conversion

Parameter	Type	Required	Description
`conversion_id`	string	yes	Conversion ID.

create_conversion Write

Create a new conversion in Tapfiliate. Associates a revenue amount with an affiliate using a unique external ID (e.g., order ID or transaction reference).

Lua path: app.integrations.tapfiliate.create_conversion
Full name: tapfiliate.tapfiliate_create_conversion

Parameter	Type	Required	Description
`affiliate_id`	string	no	The ID of the affiliate to credit when known.
`referral_code`	string	no	Affiliate referral code, matching the ref= value in referral links.
`tracking_id`	string	no	Tracking id from Tapfiliate.js.
`click_id`	string	no	Click id for additional reporting.
`coupon`	string	no	Coupon code to attribute the conversion.
`amount`	number	no	The conversion amount (e.g., 29.99).
`external_id`	string	yes	A unique external reference (e.g., order ID, transaction ID).
`program_id`	string	no	Program ID.
`currency`	string	no	Three-letter ISO currency code.
`customer_id`	string	no	Customer id for recurring or lifetime commission workflows.
`commission_type`	string	no	Commission type id.
`commissions`	array	no	Commission override array. Overrides amount and commission_type when supplied.
`meta_data`	object	no	Optional key-value metadata to attach to the conversion.

add_conversion_commission Write

Add a commission line to a Tapfiliate conversion.

Lua path: app.integrations.tapfiliate.add_conversion_commission
Full name: tapfiliate.tapfiliate_add_conversion_commission

Parameter	Type	Required	Description
`conversion_id`	string	yes	Conversion ID.
`conversion_sub_amount`	number	yes	Amount on which commission should be calculated.
`commission_type`	string	no	Optional commission type id.
`comment`	string	no	Optional affiliate-visible comment.

list_commissions Read

List Tapfiliate commissions with optional filters.

Lua path: app.integrations.tapfiliate.list_commissions
Full name: tapfiliate.tapfiliate_list_commissions

Parameter	Type	Required	Description
`affiliate_id`	string	no	Filter by affiliate ID.
`conversion_id`	string	no	Filter by conversion ID.
`program_id`	string	no	Filter by program ID.
`status`	string	no	Filter by commission status.
`date_from`	string	no	Start date filter.
`date_to`	string	no	End date filter.
`page`	integer	no	Page number.
`limit`	integer	no	Page size.

get_commission Read

Get a Tapfiliate commission by ID.

Lua path: app.integrations.tapfiliate.get_commission
Full name: tapfiliate.tapfiliate_get_commission

Parameter	Type	Required	Description
`commission_id`	string	yes	Commission ID.

list_customers Read

List Tapfiliate customers with optional program, customer, affiliate, and date filters.

Lua path: app.integrations.tapfiliate.list_customers
Full name: tapfiliate.tapfiliate_list_customers

Parameter	Type	Required	Description
`program_id`	string	no	Filter by program ID.
`customer_id`	string	no	Filter by customer ID in your system.
`affiliate_id`	string	no	Filter by affiliate ID.
`date_from`	string	no	Start date filter.
`date_to`	string	no	End date filter.

create_customer Write

Create or track a Tapfiliate customer for recurring and lifetime commission workflows.

Lua path: app.integrations.tapfiliate.create_customer
Full name: tapfiliate.tapfiliate_create_customer

Parameter	Type	Required	Description
`customer_id`	string	yes	Unique customer ID in your system.
`referral_code`	string	no	Affiliate referral code.
`tracking_id`	string	no	Tracking id from Tapfiliate.js.
`click_id`	string	no	Click id.
`coupon`	string	no	Coupon code.
`status`	string	no	Initial customer status. Defaults to new upstream.
`program_id`	string	no	Program ID.
`meta_data`	object	no	Optional metadata.

list_programs Read

List Tapfiliate affiliate programs.

Lua path: app.integrations.tapfiliate.list_programs
Full name: tapfiliate.tapfiliate_list_programs

Parameter	Type	Required	Description
No parameters.

get_program_affiliate Read

Get an affiliate enrollment within a Tapfiliate program.

Lua path: app.integrations.tapfiliate.get_program_affiliate
Full name: tapfiliate.tapfiliate_get_program_affiliate

Parameter	Type	Required	Description
`program_id`	string	yes	Program ID.
`affiliate_id`	string	yes	Affiliate ID.

update_program_affiliate Write

Update an affiliate enrollment within a Tapfiliate program.

Lua path: app.integrations.tapfiliate.update_program_affiliate
Full name: tapfiliate.tapfiliate_update_program_affiliate

Parameter	Type	Required	Description
`program_id`	string	yes	Program ID.
`affiliate_id`	string	yes	Affiliate ID.
`coupon`	string	no	Coupon code to assign to the affiliate in this program.

list_program_commission_types Read

List commission types for a Tapfiliate program.

Lua path: app.integrations.tapfiliate.list_program_commission_types
Full name: tapfiliate.tapfiliate_list_program_commission_types

Parameter	Type	Required	Description
`program_id`	string	yes	Program ID.