# Build with AI
Source: https://developers.tapfiliate.com/ai/build-with-ai

Give your coding assistant the Tapfiliate docs, so it writes integration code that works.

Coding assistants guess when they don't know an API. Connect them to these docs and they look the answer up instead: the right endpoint, the required fields, the exact header.

## Connect the docs to your assistant

This site has its own MCP server that searches and reads the documentation:

```
https://developers.tapfiliate.com/mcp
```

<Tabs>
  <Tab title="Claude Code">
    ```bash theme={null}
    claude mcp add --transport http tapfiliate-docs https://developers.tapfiliate.com/mcp
    ```
  </Tab>

  <Tab title="Cursor">
    Add to `.cursor/mcp.json` in your project:

    ```json theme={null}
    {
      "mcpServers": {
        "tapfiliate-docs": {
          "url": "https://developers.tapfiliate.com/mcp"
        }
      }
    }
    ```
  </Tab>

  <Tab title="VS Code">
    Add to `.vscode/mcp.json` in your project:

    ```json theme={null}
    {
      "servers": {
        "tapfiliate-docs": {
          "type": "http",
          "url": "https://developers.tapfiliate.com/mcp"
        }
      }
    }
    ```
  </Tab>
</Tabs>

Then ask for what you need, for example:

> Add Tapfiliate conversion tracking to our checkout. Use the tapfiliate-docs MCP server. Track the conversion from the server after the payment succeeds, with the order ID as external\_id.

<Note>
  The docs server only reads this documentation; it has no access to your account. To let an assistant work with your affiliate data, connect the [Tapfiliate MCP server](/ai/mcp).
</Note>

## Other ways in

| What | Where |
| - | - |
| Index of all pages for LLMs | [`/llms.txt`](https://developers.tapfiliate.com/llms.txt) |
| All docs in one file | [`/llms-full.txt`](https://developers.tapfiliate.com/llms-full.txt) |
| Any page as Markdown | add `.md` to its URL, for example [`/quickstart.md`](https://developers.tapfiliate.com/quickstart.md) |
| The REST API as OpenAPI 3 | [`/api-reference/openapi.json`](https://developers.tapfiliate.com/api-reference/openapi.json) — import it into Postman or Insomnia, or generate a client |

Every page also has a menu next to its title to copy it as Markdown or open it in Claude, ChatGPT or Cursor.


# MCP server
Source: https://developers.tapfiliate.com/ai/mcp

Connect Claude, Cursor and other AI assistants to your Tapfiliate account.

The Tapfiliate MCP server lets an AI assistant read your affiliate program data and analyse it for you. Ask in plain language, for example *"Which affiliates bring traffic but no sales this month?"*, and the assistant pulls live data from your account to answer.

```
https://mcp.tapfiliate.com/mcp
```

It works with any assistant that supports the [Model Context Protocol](https://modelcontextprotocol.io) over HTTP.

## Before you start

* An admin user in your Tapfiliate account, with API access.
* Tracked activity in the account: the assistant answers from your real clicks, conversions and affiliates.
* Reports by landing page, referrer or affiliate also need the Enterprise click endpoints.

You don't need an API key. The first time the assistant uses Tapfiliate, a browser window opens where you sign in and allow access.

## Connect your assistant

<Tabs>
  <Tab title="Claude">
    1. Open **Settings → Connectors** in Claude, on the web or in the desktop app.
    2. Click **Add custom connector**.
    3. Enter the name `tapfiliate` and the URL `https://mcp.tapfiliate.com/mcp`, then click **Add**.
    4. Click **Connect** next to the connector and allow access in the browser.

    If **Add custom connector** is not available, your organization admin has restricted it.
  </Tab>

  <Tab title="Claude Code">
    ```bash theme={null}
    claude mcp add --transport http tapfiliate https://mcp.tapfiliate.com/mcp
    ```

    Then run `/mcp` in Claude Code and authenticate the `tapfiliate` server.
  </Tab>

  <Tab title="Cursor">
    Open **Settings → Tools & MCP**, click **Add new MCP server** and paste:

    ```json theme={null}
    {
      "mcpServers": {
        "tapfiliate": {
          "url": "https://mcp.tapfiliate.com/mcp"
        }
      }
    }
    ```

    Save, then allow access in the browser window that opens.
  </Tab>

  <Tab title="Other clients">
    Clients that only support local servers can connect through `mcp-remote`:

    ```json theme={null}
    {
      "mcpServers": {
        "tapfiliate": {
          "command": "npx",
          "args": ["-y", "mcp-remote", "https://mcp.tapfiliate.com/mcp"]
        }
      }
    }
    ```
  </Tab>
</Tabs>

## What it can do

| Tool | What it answers |
| - | - |
| `find_traffic_without_sales_affiliates` | Affiliates with clicks but no conversions |
| `list_top_performers` | Top affiliates by revenue |
| `detect_dormant_affiliates` | Affiliates who were active and stopped |
| `detect_cvr_outliers` | Unusual conversion rates |
| `analyze_commission_structure` | How well your commission plans work |
| `get_program_health_summary` | A health summary of a program |
| `check_new_affiliate_activation` | New affiliates with no activity yet |
| `analyze_seasonal_trends` | Monthly revenue and conversion trends |
| `detect_invalid_traffic_signals` | Signs of fraud or invalid traffic |
| `get_affiliate_deep_dive` | A full review of one affiliate |
| `list_clicks`, `list_affiliates`, `list_customers`, `list_conversions` | Raw lists for your own questions |

## Access and security

* Each connection is tied to the user who allowed it and sees only that user's account.
* The tools only read data.
* To disconnect, remove the connector in your assistant.


# Create new affiliate group
Source: https://developers.tapfiliate.com/api-reference/affiliate-groups/create-new-affiliate-group

/api-reference/openapi.json post /affiliate-groups/



# List all affiliate groups
Source: https://developers.tapfiliate.com/api-reference/affiliate-groups/list-all-affiliate-groups

/api-reference/openapi.json get /affiliate-groups/



# Update affiliate group
Source: https://developers.tapfiliate.com/api-reference/affiliate-groups/update-affiliate-group

/api-reference/openapi.json patch /affiliate-groups/{affiliate_group_id}/



# Create an affiliate prospect
Source: https://developers.tapfiliate.com/api-reference/affiliate-prospects/create-an-affiliate-prospect

/api-reference/openapi.json post /affiliate-prospects/



# Delete an affiliate prospect
Source: https://developers.tapfiliate.com/api-reference/affiliate-prospects/delete-an-affiliate-prospect

/api-reference/openapi.json delete /affiliate-prospects/{affiliate_prospect_id}/



# List all affiliate prospects
Source: https://developers.tapfiliate.com/api-reference/affiliate-prospects/list-all-affiliate-prospects

/api-reference/openapi.json get /affiliate-prospects/



# Retrieve an affiliate prospect
Source: https://developers.tapfiliate.com/api-reference/affiliate-prospects/retrieve-an-affiliate-prospect

/api-reference/openapi.json get /affiliate-prospects/{affiliate_prospect_id}/



# Create an affiliate
Source: https://developers.tapfiliate.com/api-reference/affiliates/create-an-affiliate

/api-reference/openapi.json post /affiliates/



# Create note
Source: https://developers.tapfiliate.com/api-reference/affiliates/create-note

/api-reference/openapi.json post /affiliates/{affiliate_id}/notes/



# Delete an affiliate
Source: https://developers.tapfiliate.com/api-reference/affiliates/delete-an-affiliate

/api-reference/openapi.json delete /affiliates/{affiliate_id}/



# Delete meta data by key
Source: https://developers.tapfiliate.com/api-reference/affiliates/delete-meta-data-by-key

/api-reference/openapi.json delete /affiliates/{affiliate_id}/meta-data/{key}/



# Delete note
Source: https://developers.tapfiliate.com/api-reference/affiliates/delete-note

/api-reference/openapi.json delete /affiliates/{affiliate_id}/notes/{id}/



# Get affiliations
Source: https://developers.tapfiliate.com/api-reference/affiliates/get-affiliations

/api-reference/openapi.json get /affiliates/{id}/programs/



# Get custom fields
Source: https://developers.tapfiliate.com/api-reference/affiliates/get-custom-fields

/api-reference/openapi.json get /affiliates/custom-fields/



# Get payout method
Source: https://developers.tapfiliate.com/api-reference/affiliates/get-payout-method

/api-reference/openapi.json get /affiliates/{affiliate_id}/payout-methods/{payout_method_id}/



# List affiliate's payments
Source: https://developers.tapfiliate.com/api-reference/affiliates/list-affiliates-payments

/api-reference/openapi.json get /affiliates/{affiliate_id}/payments/



# List all affiliates
Source: https://developers.tapfiliate.com/api-reference/affiliates/list-all-affiliates

/api-reference/openapi.json get /affiliates/



# List notes
Source: https://developers.tapfiliate.com/api-reference/affiliates/list-notes

/api-reference/openapi.json get /affiliates/{affiliate_id}/notes/



# List payout methods
Source: https://developers.tapfiliate.com/api-reference/affiliates/list-payout-methods

/api-reference/openapi.json get /affiliates/{affiliate_id}/payout-methods/



# Remove affiliate group
Source: https://developers.tapfiliate.com/api-reference/affiliates/remove-affiliate-group

/api-reference/openapi.json delete /affiliates/{affiliate_id}/group/



# Remove parent
Source: https://developers.tapfiliate.com/api-reference/affiliates/remove-parent

/api-reference/openapi.json delete /affiliates/{child_affiliate_id}/parent/



# Retrieve affiliate's balances
Source: https://developers.tapfiliate.com/api-reference/affiliates/retrieve-affiliates-balances

/api-reference/openapi.json get /affiliates/{affiliate_id}/balances/



# Retrieve an affiliate
Source: https://developers.tapfiliate.com/api-reference/affiliates/retrieve-an-affiliate

/api-reference/openapi.json get /affiliates/{affiliate_id}/



# Retrieve meta data
Source: https://developers.tapfiliate.com/api-reference/affiliates/retrieve-meta-data

/api-reference/openapi.json get /affiliates/{affiliate_id}/meta-data/



# Retrieve meta data by key
Source: https://developers.tapfiliate.com/api-reference/affiliates/retrieve-meta-data-by-key

/api-reference/openapi.json get /affiliates/{affiliate_id}/meta-data/{key}/



# Set affiliate group
Source: https://developers.tapfiliate.com/api-reference/affiliates/set-affiliate-group

/api-reference/openapi.json put /affiliates/{affiliate_id}/group/



# Set meta data by key
Source: https://developers.tapfiliate.com/api-reference/affiliates/set-meta-data-by-key

/api-reference/openapi.json put /affiliates/{affiliate_id}/meta-data/{key}/



# Set parent
Source: https://developers.tapfiliate.com/api-reference/affiliates/set-parent

/api-reference/openapi.json post /affiliates/{child_affiliate_id}/parent/



# Set payout method
Source: https://developers.tapfiliate.com/api-reference/affiliates/set-payout-method

/api-reference/openapi.json put /affiliates/{affiliate_id}/payout-methods/{payout_method_id}/
The body of the request should contain the appropriate data for the payout method you are setting. The field ids can be found by exporting payouts as .csv on the payouts page.



# Update note
Source: https://developers.tapfiliate.com/api-reference/affiliates/update-note

/api-reference/openapi.json put /affiliates/{affiliate_id}/notes/{id}/



# Update (replace) meta data
Source: https://developers.tapfiliate.com/api-reference/affiliates/update-replace-meta-data

/api-reference/openapi.json put /affiliates/{affiliate_id}/meta-data/



# Create a click
Source: https://developers.tapfiliate.com/api-reference/clicks/create-a-click

/api-reference/openapi.json post /clicks/
In case you elect to use a REST-only implementation, you can use the "Create a Click" endpoint to obtain a click id. This click id can be used to create a conversion, by passing it as the `click_id`. You can learn how to set up a full REST-only integration in our [REST integration guide](https://support.tapfiliate.com/en/articles/12682358-how-to-integrate-with-tapfiliate-via-the-rest-api)



# Get detailed information about click
Source: https://developers.tapfiliate.com/api-reference/clicks/get-detailed-information-about-click

/api-reference/openapi.json get /clicks/{id}/



# List all clicks
Source: https://developers.tapfiliate.com/api-reference/clicks/list-all-clicks

/api-reference/openapi.json get /clicks/



# Approve a commission
Source: https://developers.tapfiliate.com/api-reference/commissions/approve-a-commission

/api-reference/openapi.json put /commissions/{commission_id}/approved/



# Disapprove a commission
Source: https://developers.tapfiliate.com/api-reference/commissions/disapprove-a-commission

/api-reference/openapi.json delete /commissions/{commission_id}/approved/



# List all commissions
Source: https://developers.tapfiliate.com/api-reference/commissions/list-all-commissions

/api-reference/openapi.json get /commissions/



# Retrieve a commission
Source: https://developers.tapfiliate.com/api-reference/commissions/retrieve-a-commission

/api-reference/openapi.json get /commissions/{commission_id}/



# Update a commission
Source: https://developers.tapfiliate.com/api-reference/commissions/update-a-commission

/api-reference/openapi.json patch /commissions/{commission_id}/



# Add commissions to a conversion
Source: https://developers.tapfiliate.com/api-reference/conversions/add-commissions-to-a-conversion

/api-reference/openapi.json post /conversions/{conversion_id}/commissions/



# Create a conversion
Source: https://developers.tapfiliate.com/api-reference/conversions/create-a-conversion

/api-reference/openapi.json post /conversions/
You are required to use either a referral code, customer_id, click id, coupon code, tracking id, or asset_id & source_id combination. If more than one of these is sent, the precedence will be as follows (highest to lowest): Customer id, Coupon, Referral Code, Click Id, Asset id + Source id, Tracking id



# Delete a conversion
Source: https://developers.tapfiliate.com/api-reference/conversions/delete-a-conversion

/api-reference/openapi.json delete /conversions/{conversion_id}/



# Delete meta data by key
Source: https://developers.tapfiliate.com/api-reference/conversions/delete-meta-data-by-key

/api-reference/openapi.json delete /conversions/{conversion_id}/meta-data/{key}/



# List all conversions
Source: https://developers.tapfiliate.com/api-reference/conversions/list-all-conversions

/api-reference/openapi.json get /conversions/



# Retrieve a conversion
Source: https://developers.tapfiliate.com/api-reference/conversions/retrieve-a-conversion

/api-reference/openapi.json get /conversions/{conversion_id}/



# Retrieve meta data
Source: https://developers.tapfiliate.com/api-reference/conversions/retrieve-meta-data

/api-reference/openapi.json get /conversions/{conversion_id}/meta-data/



# Retrieve meta data by key
Source: https://developers.tapfiliate.com/api-reference/conversions/retrieve-meta-data-by-key

/api-reference/openapi.json get /conversions/{conversion_id}/meta-data/{key}/



# Set meta data by key
Source: https://developers.tapfiliate.com/api-reference/conversions/set-meta-data-by-key

/api-reference/openapi.json put /conversions/{conversion_id}/meta-data/{key}/



# Update a conversion
Source: https://developers.tapfiliate.com/api-reference/conversions/update-a-conversion

/api-reference/openapi.json patch /conversions/{conversion_id}/



# Update (replace) meta data
Source: https://developers.tapfiliate.com/api-reference/conversions/update-replace-meta-data

/api-reference/openapi.json put /conversions/{conversion_id}/meta-data/



# Cancel a customer
Source: https://developers.tapfiliate.com/api-reference/customers/cancel-a-customer

/api-reference/openapi.json delete /customers/{id}/status/



# Create a customer
Source: https://developers.tapfiliate.com/api-reference/customers/create-a-customer

/api-reference/openapi.json post /customers/
You are required to use either a Tracking id, referral code, click id, coupon code, or asset_id & source_id combination. If more than one of these is sent, the precedence will be as follows (highest to lowest): Coupon, Referral Code, Click Id, Asset id + Source id, Tracking id

Please refer to our [REST API integration guide](https://support.tapfiliate.com/en/articles/12682358-how-to-integrate-with-tapfiliate-via-the-rest-api) for more info.



# Delete a customer
Source: https://developers.tapfiliate.com/api-reference/customers/delete-a-customer

/api-reference/openapi.json delete /customers/{id}/



# Delete meta data by key
Source: https://developers.tapfiliate.com/api-reference/customers/delete-meta-data-by-key

/api-reference/openapi.json delete /customers/{id}/meta-data/{key}/



# List all customers
Source: https://developers.tapfiliate.com/api-reference/customers/list-all-customers

/api-reference/openapi.json get /customers/



# Retrieve a customer
Source: https://developers.tapfiliate.com/api-reference/customers/retrieve-a-customer

/api-reference/openapi.json get /customers/{id}/



# Retrieve meta data
Source: https://developers.tapfiliate.com/api-reference/customers/retrieve-meta-data

/api-reference/openapi.json get /customers/{id}/meta-data/



# Retrieve meta data by key
Source: https://developers.tapfiliate.com/api-reference/customers/retrieve-meta-data-by-key

/api-reference/openapi.json get /customers/{id}/meta-data/{key}/



# Set meta data by key
Source: https://developers.tapfiliate.com/api-reference/customers/set-meta-data-by-key

/api-reference/openapi.json put /customers/{id}/meta-data/{key}/



# Uncancel a customer
Source: https://developers.tapfiliate.com/api-reference/customers/uncancel-a-customer

/api-reference/openapi.json put /customers/{id}/status/
The customer will jump back to the appropriate status. You can read more about status [statuses here](https://support.tapfiliate.com/en/articles/3092024-what-are-customers#customer-status)



# Update a customer
Source: https://developers.tapfiliate.com/api-reference/customers/update-a-customer

/api-reference/openapi.json patch /customers/{id}/



# Update (replace) meta data
Source: https://developers.tapfiliate.com/api-reference/customers/update-replace-meta-data

/api-reference/openapi.json put /customers/{id}/meta-data/



# Errors
Source: https://developers.tapfiliate.com/api-reference/errors

Error formats of the REST API and the messages integrations run into most often.

<Tip>
  Send `Accept: application/json` with every request. Without it, some errors (for example `401` without a key, or `404` for an unknown path) come back as an HTML page instead of JSON.
</Tip>

## Formats

Errors come in two shapes, depending on where the request stopped.

**Business and validation errors** — `400`, `403`, `404` and `409` raised by an endpoint — return a list of errors:

```json theme={null}
{
  "errors": [
    { "message": "Duplicate conversion. There is already a conversion for External id 'ORD123'" }
  ]
}
```

Validation errors also name the field: `property_path` and `message_raw`. `409` errors carry a machine-readable `code`.

**Request-level errors** — a missing key, no access, an unknown path or a server error — return a single object:

```json theme={null}
{ "message": "Not Found", "code": 404, "traceId": "7ae8e92b77572da0…" }
```

If something goes wrong on our side, send the `traceId` to support: it lets us find your request.

A wrong API key always returns `{"message": "Authentication Failed.", "code": 401}`.

## Status codes

| Status | Meaning |
| - | - |
| `400` | The request is invalid. The message says what to change. |
| `401` | The API key is missing or wrong. |
| `403` | Your user has no API access, lacks the permission for this action, or the feature isn't on your plan. |
| `404` | The path or the object doesn't exist, or belongs to another account. |
| `405` | The endpoint doesn't support this HTTP method. |
| `409` | The object is in a state that doesn't allow the change, see [conflicts](#conflicts). |
| `429` | Too many requests, see [rate limits](/api-reference/introduction#rate-limits). |
| `5xx` | Something went wrong on our side. Retry later with a delay and send the `traceId` to support if it persists. |

## Common errors when tracking

These come from **Create a conversion**, **Create a customer** and the [postbacks](/tracking/server-to-server). Messages are quoted exactly as the API returns them, so you can match them in your logs.

| Message | What happened | What to do |
| - | - | - |
| `Missing mandatory parameter(s)` | No way to attribute the conversion was sent. | Send `referral_code`, `coupon`, `click_id` or `asset_id` with `source_id`. |
| `Parameter '…' takes precedence for tracking, but no value was passed` | The highest-priority field was sent empty, for example `"coupon": ""`. | Leave out fields you don't have instead of sending them empty. |
| `Unknown referral code`, `Unknown coupon code`, `Invalid click id` | The value doesn't match an affiliate in your account. | Check the value you pass on. |
| `Cookie expired` | The affiliate's click is older than the program's cookie time. | Expected for late conversions. To track anyway, add `?override_max_cookie_time=true`. |
| `Duplicate conversion. There is already a conversion for External id '…'` | A conversion with this `external_id` already exists. | Treat it as recorded. Look it up with `GET /conversions/?external_id=…` if needed. |
| `To many concurrent attempts to create conversion with id '…'` | A retry arrived within 10 seconds of a failed attempt with the same ID. | Wait more than 10 seconds before retrying. |
| `Missing tracking parameter value and no customer found for customer id: …` | Only `customer_id` was sent, and no such customer exists. | Create the customer first, or send a tracking parameter too. |
| `Affiliate is not approved for this program`, `Affiliate is deleted` | The affiliate can't earn in this program. | Approve the affiliate in the program. |
| `Program is archived` | The program no longer accepts conversions. | Track to an active program. |
| `Duplicate customer. There is already a customer for Customer id '…'` | The customer exists already. | Use the existing customer. |
| `Invalid status '…'. Valid are 'new', 'trial', 'lead'` | Unknown initial customer status. | Use one of the listed values. |
| `Request body was not valid JSON` | The body isn't a JSON object. | Send a JSON object with `Content-Type: application/json`. |
| `Advertiser account locked` | Your account is locked. | Contact support. |

When listing, `Invalid date` means `date_from` or `date_to` isn't a valid `YYYY-MM-DD` date.

## Conflicts

`409` responses explain why the object can't change and include a `code`:

| `code` | Meaning |
| - | - |
| `commission_approved` | The commission is approved and your account uses Tapfiliate Pay, so it can't be disapproved or approved again. |
| `commission_unfunded` | The commission can't be approved: your Tapfiliate Pay balance doesn't cover what is already owed. |
| `program_archived` | The program is archived and can't be modified. |


# API reference
Source: https://developers.tapfiliate.com/api-reference/introduction

Base URL, versioning, pagination, rate limits and errors of the Tapfiliate REST API.

The Tapfiliate REST API has resource-oriented URLs, accepts and returns JSON, and uses standard HTTP methods and status codes.

```
https://api.tapfiliate.com/1.6
```

Every request needs your API key in the `X-Api-Key` header, see [Authentication](/authentication). Also send `Accept: application/json`, so errors come back as JSON too.

## Versions

This reference describes version **1.6**. The version is part of the path of every request.

[Server-to-server postbacks](/tracking/server-to-server) use the `/1.7/pb/` endpoints.

## Pagination

Endpoints that return lists are paginated, 25 items per page. Ask for further pages with the `page` parameter; numbering starts at 1.

```bash theme={null}
curl "https://api.tapfiliate.com/1.6/conversions/?page=2" \
  -H "X-Api-Key: YOUR_API_KEY"
```

Links to other pages come in the `Link` header:

```
Link: <https://api.tapfiliate.com/1.6/conversions/?page=3>; rel="next",
      <https://api.tapfiliate.com/1.6/conversions/?page=51>; rel="last"
```

| `rel` | Page |
| - | - |
| `next` | The next page |
| `prev` | The previous page |
| `first` | The first page |
| `last` | The last page |

To read a whole list, follow `rel="next"` until it is absent.

## Rate limits

Limits apply per API key and per endpoint, in a fixed window that starts with your first request.

| Limit | Endpoints |
| - | - |
| 10 per minute | List all balances |
| 100 per minute | Get detailed information about a click |
| 900 per minute | List all conversions, list all clicks |
| 1,500 per 5 minutes | Affiliates, affiliate prospects and programs; list customers and commissions; retrieve a customer or a conversion |
| 300 per 15 minutes | Meta data and notes, affiliate groups, payments |

Responses of limited endpoints carry these headers:

| Header | Meaning |
| - | - |
| `X-RateLimit-Limit` | Requests allowed in the current window |
| `X-RateLimit-Remaining` | Requests left in the current window |
| `X-RateLimit-Reset` | When the window resets, as a Unix timestamp in seconds |

Over the limit, the API answers `429 Too Many Requests` with a plain-text body and no `Retry-After` header. Wait until `X-RateLimit-Reset`, then continue.

Other endpoints, such as creating conversions and customers, have no fixed limit today. Handle `429` everywhere anyway, so your integration keeps working if limits change.

## Errors

The API uses standard HTTP status codes and returns a JSON body explaining the error. [Errors](/api-reference/errors) lists the formats and the messages integrations run into most often.

## Conventions

* Timestamps are ISO 8601 with a UTC offset, for example `2021-03-03T12:39:19+0000`.
* Properties without a value are returned as `null`, not omitted.
* IDs of affiliates and programs are strings, for example `janejameson` or `johns-affiliate-program`.


# Cancel payment
Source: https://developers.tapfiliate.com/api-reference/payments/cancel-payment

/api-reference/openapi.json delete /payments/{id}/
Cancels the payment and re-adds the amount to the affiliate's balance



# Create a payment
Source: https://developers.tapfiliate.com/api-reference/payments/create-a-payment

/api-reference/openapi.json post /payments/
Create a single payment or multiple (using an array of payments)



# List all balances
Source: https://developers.tapfiliate.com/api-reference/payments/list-all-balances

/api-reference/openapi.json get /balances/
Returns a **non-paginated** list of all non-zero affiliate balances.



# List all payments
Source: https://developers.tapfiliate.com/api-reference/payments/list-all-payments

/api-reference/openapi.json get /payments/



# Retrieve payment
Source: https://developers.tapfiliate.com/api-reference/payments/retrieve-payment

/api-reference/openapi.json get /payments/{id}/



# Add an affiliate to a program
Source: https://developers.tapfiliate.com/api-reference/programs/add-an-affiliate-to-a-program

/api-reference/openapi.json post /programs/{program_id}/affiliates/



# Approve an affiliate
Source: https://developers.tapfiliate.com/api-reference/programs/approve-an-affiliate

/api-reference/openapi.json put /programs/{program_id}/affiliates/{affiliate_id}/approved/



# Disapprove an affiliate
Source: https://developers.tapfiliate.com/api-reference/programs/disapprove-an-affiliate

/api-reference/openapi.json delete /programs/{program_id}/affiliates/{affiliate_id}/approved/



# List all affiliates in program
Source: https://developers.tapfiliate.com/api-reference/programs/list-all-affiliates-in-program

/api-reference/openapi.json get /programs/{program_id}/affiliates/



# List all programs
Source: https://developers.tapfiliate.com/api-reference/programs/list-all-programs

/api-reference/openapi.json get /programs/



# List program bonuses
Source: https://developers.tapfiliate.com/api-reference/programs/list-program-bonuses

/api-reference/openapi.json get /programs/{program_id}/bonuses/



# List program commission types
Source: https://developers.tapfiliate.com/api-reference/programs/list-program-commission-types

/api-reference/openapi.json get /programs/{program_id}/commission-types/



# List program MLM levels
Source: https://developers.tapfiliate.com/api-reference/programs/list-program-mlm-levels

/api-reference/openapi.json get /programs/{program_id}/levels/



# Retrieve a program
Source: https://developers.tapfiliate.com/api-reference/programs/retrieve-a-program

/api-reference/openapi.json get /programs/{program_id}/



# Retrieve an affiliate in a program
Source: https://developers.tapfiliate.com/api-reference/programs/retrieve-an-affiliate-in-a-program

/api-reference/openapi.json get /programs/{program_id}/affiliates/{affiliate_id}/



# Update an affiliate in a program
Source: https://developers.tapfiliate.com/api-reference/programs/update-an-affiliate-in-a-program

/api-reference/openapi.json patch /programs/{program_id}/affiliates/{affiliate_id}/



# Authentication
Source: https://developers.tapfiliate.com/authentication

Authenticate API requests with your API key.

Every request to the REST API carries your API key in the `X-Api-Key` header:

```bash theme={null}
curl https://api.tapfiliate.com/1.6/conversions/ \
  -H "X-Api-Key: YOUR_API_KEY"
```

Send the key exactly as it is shown in your account, without quotes or extra spaces. All requests must use HTTPS.

## Where to find your key

Your API key is in your [profile settings](https://app.tapfiliate.com/a/profile/) in the Tapfiliate dashboard. The [help center](https://support.tapfiliate.com/en/articles/12793297-how-to-find-account-id-and-api-key) shows the exact place.

The key belongs to your user in one advertiser account and acts with your permissions there. It is not scoped to a single program or to read-only access.

## Keep it secret

<Warning>
  Your API key can approve commissions and change affiliate data. Use it only from your server.
</Warning>

* Do not put it in browser code. For tracking from the browser use [tapfiliate.js](/tracking/javascript), which needs only your public account ID.
* Do not commit it to a repository or paste it into tickets and chats.
* If the key has leaked, regenerate it in your profile settings. The old key stops working immediately, including in webhooks and integrations that use it.

## Errors

| Status | Meaning |
| - | - |
| `401` | The key is missing or wrong. A wrong key returns `{"message": "Authentication Failed.", "code": 401}`. |
| `403` | The key is valid, but your user has no API access. Ask the account owner to grant the API access permission, or contact support. |

## Connecting AI assistants

The [MCP server](/ai/mcp) does not use your API key. It signs you in with OAuth, so you never paste the key into an AI tool.


# Webhooks
Source: https://developers.tapfiliate.com/automation/webhooks

Send events from Tapfiliate to your systems with trigger webhooks.

Triggers run an action when something happens in your program. A webhook trigger sends a request to your URL, so your systems learn about new affiliates, conversions or commissions without polling the API.

## Events

| Event | Fires when |
| - | - |
| Affiliate created | Someone signs up as an affiliate or is added manually. |
| Affiliate added to program | An affiliate applies to a program or is added to it. |
| Affiliate approved for program | An affiliate is approved, automatically or manually. |
| Affiliate disapproved for program | An affiliate is disapproved for a program. |
| Affiliate added to group | An affiliate is added to an affiliate group. |
| Affiliate prospect created | A recruitment source creates an affiliate prospect. |
| Affiliate prospect promoted | A prospect becomes an affiliate. |
| Conversion created | A conversion is created. |
| Commission created | A commission is created: from a conversion, a recurring or MLM commission, or the API. |
| Commission updated | A commission is approved, disapproved or edited. |
| Customer created | A customer is created. |
| Customer updated | A customer is updated. |
| Payment created | An affiliate's balance is settled. |

Most events have **filters**, so the webhook fires only when conditions match, for example only for one program or only when an affiliate initiated the event. Open **Add filter** in the trigger to see the filters of an event.

## Set up a webhook

<Steps>
  <Step title="Create a trigger">
    Open **Triggers** in your dashboard and click **New trigger**. Choose the event.
  </Step>

  <Step title="Add filters">
    Optional. Narrow down when the trigger fires.
  </Step>

  <Step title="Choose the webhook type">
    * **Webhook** sends the object in the same format as the [API reference](/api-reference/introduction), for example a conversion for *Conversion created*.
    * **Webhook (custom)** lets you compose the request yourself. Use merge tags from the `{…}` menu next to the field to insert event data.
  </Step>

  <Step title="Save">
    The webhook starts firing on the next matching event.
  </Step>
</Steps>

<Tip>
  Track a test conversion after saving, to see the payload arrive at your endpoint.
</Tip>

## Handling webhooks

* Respond with a `2xx` status quickly and do the work asynchronously.
* Make your handler idempotent: use the object's `id` to skip events you have already processed.
* Use the [REST API](/api-reference/introduction) to fetch the current state of an object when you need more than the payload.


# Zapier
Source: https://developers.tapfiliate.com/automation/zapier

Connect Tapfiliate to thousands of apps without code.

The [Tapfiliate app on Zapier](https://zapier.com/apps/tapfiliate/integrations) connects your program to CRMs, billing tools, spreadsheets and messengers without writing code. Typical uses:

* create a conversion when a payment succeeds in your billing tool;
* add new affiliates to your CRM or newsletter;
* post new conversions or commissions to a team channel.

To connect, sign in to Zapier, add the Tapfiliate app and connect your Tapfiliate account when asked. Your user needs API access, as described in [Authentication](/authentication).

For logic Zapier can't express, use [webhooks](/automation/webhooks) and the [REST API](/api-reference/introduction) directly.


# Tapfiliate for developers
Source: https://developers.tapfiliate.com/index

Track affiliate referrals, automate your partner program and build on the Tapfiliate API.

Tapfiliate tracks clicks, customers and conversions that your affiliates bring in, and turns them into commissions and payouts. This portal covers everything you need to connect your product to it.

<CardGroup>
  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Make your first API request and track your first conversion.
  </Card>

  <Card title="API reference" icon="code" href="/api-reference/introduction">
    Every endpoint of the REST API, with a playground for read requests.
  </Card>

  <Card title="JavaScript tracking" icon="js" href="/tracking/javascript">
    Track clicks, customers and conversions from your website.
  </Card>

  <Card title="Server-to-server" icon="server" href="/tracking/server-to-server">
    Track conversions from your backend with a single request.
  </Card>

  <Card title="Webhooks" icon="bolt" href="/automation/webhooks">
    Get notified when affiliates, conversions or commissions change.
  </Card>

  <Card title="MCP server" icon="robot" href="/ai/mcp">
    Connect Claude, Cursor or another AI assistant to your account.
  </Card>

  <Card title="Build with AI" icon="wand-magic-sparkles" href="/ai/build-with-ai">
    Give your coding assistant these docs, so it writes integration code that works.
  </Card>

  <Card title="Status" icon="signal" href="https://status.tapfiliate.com">
    Current status of Tapfiliate services and past incidents.
  </Card>
</CardGroup>

## How tracking works

<Steps>
  <Step title="A visitor clicks an affiliate link">
    The link carries the affiliate's referral code, for example `?ref=janejameson`. Tapfiliate records a click and remembers the affiliate in a first-party cookie.
  </Step>

  <Step title="The visitor signs up or buys">
    You report it to Tapfiliate from the browser with [tapfiliate.js](/tracking/javascript) or from your server with the [REST API](/api-reference/introduction) or a [postback](/tracking/server-to-server).
  </Step>

  <Step title="Tapfiliate creates a conversion and commissions">
    Commissions follow the rules of your program. You approve them, and they are paid out to the affiliate.
  </Step>
</Steps>

## Need help?

For questions about your account and program settings, see the [help center](https://support.tapfiliate.com) or contact support from your dashboard.


# Quickstart
Source: https://developers.tapfiliate.com/quickstart

Make your first API request and track your first conversion in a few minutes.

## 1. Get your API key

Log in to Tapfiliate and copy your API key from your [profile settings](https://app.tapfiliate.com/a/profile/). The [help center](https://support.tapfiliate.com/en/articles/12793297-how-to-find-account-id-and-api-key) shows where to find it, together with your account ID that tapfiliate.js needs.

<Warning>
  Your API key can approve commissions. Keep it on your server: never put it in frontend code, a public repository or a support ticket.
</Warning>

## 2. Make your first request

List the programs in your account:

```bash theme={null}
curl https://api.tapfiliate.com/1.6/programs/ \
  -H "X-Api-Key: YOUR_API_KEY"
```

A `200` response with a JSON array of programs means your key works. See [Authentication](/authentication) if you get `401` or `403`.

## 3. Track a conversion

Pick the way that matches where you know about the sale.

<Tabs>
  <Tab title="In the browser">
    Add tapfiliate.js to every page so clicks on affiliate links are detected:

    ```html theme={null}
    <script src="https://script.tapfiliate.com/tapfiliate.js" type="text/javascript" async></script>
    <script type="text/javascript">
      (function(t,a,p){t.TapfiliateObject=a;t[a]=t[a]||function(){
      (t[a].q=t[a].q||[]).push(arguments)}})(window,'tap');

      tap('create', 'YOUR_ACCOUNT_ID');
      tap('detect');
    </script>
    ```

    Then report the sale on your thank-you page:

    ```js theme={null}
    tap('conversion', 'ORD123', 49.99);
    ```

    The conversion is only created when the visitor came through an affiliate. See [JavaScript tracking](/tracking/javascript) for customers, trials and multiple commissions.
  </Tab>

  <Tab title="From your server">
    Send the order with the affiliate's referral code, coupon or click ID:

    <CodeGroup>
      ```bash cURL theme={null}
      curl -X POST https://api.tapfiliate.com/1.6/conversions/ \
        -H "X-Api-Key: YOUR_API_KEY" \
        -H "Content-Type: application/json" \
        -d '{
          "referral_code": "janejameson",
          "external_id": "ORD123",
          "amount": 49.99
        }'
      ```

      ```js Node.js theme={null}
      const response = await fetch('https://api.tapfiliate.com/1.6/conversions/', {
        method: 'POST',
        headers: {
          'X-Api-Key': process.env.TAPFILIATE_API_KEY,
          'Content-Type': 'application/json',
        },
        body: JSON.stringify({
          referral_code: 'janejameson',
          external_id: 'ORD123',
          amount: 49.99,
        }),
      });

      if (!response.ok) {
        throw new Error(`Tapfiliate: ${response.status} ${await response.text()}`);
      }
      const conversion = await response.json();
      ```

      ```python Python theme={null}
      import os
      import requests

      response = requests.post(
          "https://api.tapfiliate.com/1.6/conversions/",
          headers={"X-Api-Key": os.environ["TAPFILIATE_API_KEY"]},
          json={"referral_code": "janejameson", "external_id": "ORD123", "amount": 49.99},
          timeout=10,
      )
      response.raise_for_status()
      conversion = response.json()
      ```

      ```php PHP theme={null}
      $ch = curl_init('https://api.tapfiliate.com/1.6/conversions/');
      curl_setopt_array($ch, [
          CURLOPT_POST => true,
          CURLOPT_RETURNTRANSFER => true,
          CURLOPT_TIMEOUT => 10,
          CURLOPT_HTTPHEADER => [
              'X-Api-Key: ' . getenv('TAPFILIATE_API_KEY'),
              'Content-Type: application/json',
          ],
          CURLOPT_POSTFIELDS => json_encode([
              'referral_code' => 'janejameson',
              'external_id' => 'ORD123',
              'amount' => 49.99,
          ]),
      ]);
      $conversion = json_decode(curl_exec($ch), true);
      $status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
      curl_close($ch);
      ```
    </CodeGroup>

    `external_id` is your order ID. A second request with the same `external_id` is rejected with `400 Duplicate conversion`, so a retry never counts a sale twice. See [Create a conversion](/api-reference/conversions/create-a-conversion) for every field.
  </Tab>
</Tabs>

## 4. Check it in your dashboard

Open the conversions report in your Tapfiliate dashboard: the conversion appears there with its commission. Run a test like this before you launch your program, so you know tracking works end to end.

## Next steps

<CardGroup>
  <Card title="API reference" icon="code" href="/api-reference/introduction">
    Pagination, rate limits and every endpoint.
  </Card>

  <Card title="Webhooks" icon="bolt" href="/automation/webhooks">
    React to new conversions and commissions.
  </Card>
</CardGroup>


# Track sales from a custom or third-party checkout
Source: https://developers.tapfiliate.com/recipes/custom-checkout

Keep the affiliate's click with the order and create the conversion from your server when the payment succeeds.

Use this recipe when the sale happens somewhere tapfiliate.js can't report it: in your own backend, in an external checkout or billing system, or on another domain.

The idea is simple. The browser records the affiliate's click. You carry the click to the place that learns about the payment. That place creates the conversion through the API.

<Steps>
  <Step title="Record the click in the browser">
    Add tapfiliate.js to every page where affiliate links can land, as described in [JavaScript tracking](/tracking/javascript). Then keep an identifier of the click. There are two, pick one.

    <Tabs>
      <Tab title="Click ID">
        When `detect` records a click, its callback receives the click. Store `click.id` in your own first-party cookie:

        ```html theme={null}
        <script src="https://script.tapfiliate.com/tapfiliate.js" type="text/javascript" async></script>
        <script type="text/javascript">
          (function(t,a,p){t.TapfiliateObject=a;t[a]=t[a]||function(){
          (t[a].q=t[a].q||[]).push(arguments)}})(window,'tap');

          tap('create', 'YOUR_ACCOUNT_ID');
          tap('detect', {}, function (click) {
            // Runs only when the visitor arrived through an affiliate link.
            document.cookie = 'affiliate_click_id=' + encodeURIComponent(click.id) +
              '; path=/; max-age=2592000; SameSite=Lax';
          });
        </script>
        ```

        The callback runs only on the page view where the click is recorded. A visitor who returns later without an affiliate link keeps the cookie you set.

        A click ID points to exactly one click. Prefer it when you can store it.
      </Tab>

      <Tab title="Tracking ID">
        `getTrackingId` returns the visitor IDs that tapfiliate.js keeps in this browser, joined with `__`. Call it on any page that runs the snippet, after `tap('create', …)`, for example on the checkout page:

        ```js theme={null}
        tap('getTrackingId', {}, function (trackingId) {
          // null if this browser has no Tapfiliate visitor ID.
          if (trackingId) {
            document.getElementById('affiliate_tracking_id').value = trackingId;
          }
        });
        ```

        When you send a tracking ID, Tapfiliate looks up the visitor's most recent click. If there is none, the conversion fails with `No click found for visitor id`.
      </Tab>
    </Tabs>
  </Step>

  <Step title="Carry it to the checkout">
    The ID has to reach the system that will know about the payment.

    * **Your own backend.** Read the cookie on the request that creates the order, or send the ID in a hidden form field. Save it on the order.
    * **An external checkout or billing system.** If it lets you attach your own data to a payment and sends that data back in its payment notification, put the ID there. A URL parameter on the checkout link or a hidden field in the checkout form works the same way.
    * **Another domain.** Cookies don't travel between domains. Add the ID to the link or the form that takes the visitor there.

    ```html theme={null}
    <form method="post" action="/checkout">
      <input type="hidden" name="affiliate_click_id" id="affiliate_click_id">
      <!-- your checkout fields -->
    </form>
    <script>
      var match = document.cookie.match(/(?:^|; )affiliate_click_id=([^;]*)/);
      if (match) document.getElementById('affiliate_click_id').value = decodeURIComponent(match[1]);
    </script>
    ```

    No ID means Tapfiliate recorded no affiliate click for this visitor. Don't send a conversion for that order.
  </Step>

  <Step title="Create the conversion when the payment succeeds">
    From your server, send the stored ID with your order ID and amount. Use `click_id` or `tracking_id`, whichever you stored.

    <CodeGroup>
      ```bash cURL theme={null}
      curl -X POST https://api.tapfiliate.com/1.6/conversions/ \
        -H "X-Api-Key: YOUR_API_KEY" \
        -H "Content-Type: application/json" \
        -H "Accept: application/json" \
        -d '{
          "click_id": "CLICK_ID_FROM_THE_ORDER",
          "external_id": "ORD123",
          "amount": 49.99,
          "currency": "EUR"
        }'
      ```

      ```js Node.js theme={null}
      // Call this from the handler that learns the payment has succeeded.
      async function trackConversion(order) {
        if (!order.affiliateClickId) return null; // not referred by an affiliate

        const response = await fetch('https://api.tapfiliate.com/1.6/conversions/', {
          method: 'POST',
          headers: {
            'X-Api-Key': process.env.TAPFILIATE_API_KEY,
            'Content-Type': 'application/json',
            Accept: 'application/json',
          },
          body: JSON.stringify({
            click_id: order.affiliateClickId,
            external_id: order.id,
            amount: order.total,
            currency: order.currency,
          }),
        });

        if (response.ok) return response.json();

        const body = await response.json().catch(() => null);
        const message = body?.errors?.[0]?.message ?? '';

        // Already tracked, for example by an earlier attempt: nothing to do.
        if (message.startsWith('Duplicate conversion')) return null;

        throw new Error(`Tapfiliate ${response.status}: ${message}`);
      }
      ```
    </CodeGroup>

    | Field | Description |
    | - | - |
    | `click_id` or `tracking_id` | The ID you stored in step 1. |
    | `external_id` | Your order or payment ID. Unique per conversion in your account, see [retries](#retries-and-duplicates). |
    | `amount` | The order amount. Commissions are calculated from it. |
    | `currency` | Three-letter ISO code of `amount`. Without it, or with a code Tapfiliate doesn't know, the program currency is used. |

    A `200` response is the created conversion, with its affiliate and commissions. All fields are in [Create a conversion](/api-reference/conversions/create-a-conversion).
  </Step>

  <Step title="Confirm it worked">
    * Set up a webhook for the **Conversion created** event, see [Webhooks](/automation/webhooks). It fires for conversions created through the API.
    * Or look the conversion up by your order ID:

    ```bash theme={null}
    curl "https://api.tapfiliate.com/1.6/conversions/?external_id=ORD123" \
      -H "X-Api-Key: YOUR_API_KEY"
    ```

    Track a test sale through the whole flow before you launch.
  </Step>
</Steps>

## No JavaScript on the landing page

If affiliate links land where you can't run tapfiliate.js, create the click from your server. Read the affiliate's referral code from the landing URL (the `ref` parameter by default) and send it with the visitor's details:

```bash theme={null}
curl -X POST https://api.tapfiliate.com/1.6/clicks/ \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "referral_code": "janejameson",
    "landing_page": "https://example.com/pricing?ref=janejameson",
    "referrer": "https://janes-blog.example/review",
    "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/129.0 Safari/537.36",
    "ip": "203.0.113.7"
  }'
```

The response holds only the click ID:

```json theme={null}
{ "id": "5f0c7a2e-8b1d-11ef-9c3a-0242ac120002" }
```

Save it on the visitor's session or order and use it as `click_id` in step 3.

| Field | Description |
| - | - |
| `referral_code` | The affiliate's referral code. Instead, you can send `asset_id` and `source_id` from the affiliate's link. One of the two is required. |
| `landing_page`, `referrer` | The page the visitor landed on and where they came from. |
| `user_agent`, `ip` | The visitor's browser and IP address. Tapfiliate stores only what you send: it doesn't take them from your server's request. |

Errors:

* `404` — the referral code doesn't exist in your account, or the asset or source doesn't exist.
* `400` — neither a referral code nor `asset_id` with `source_id` was sent, `ip` isn't a valid IP address, or the affiliate isn't approved in the program. The body says only `Bad Request`, so check these three.
* `400 Program is archived` — the program no longer accepts clicks.

## Which identifier wins

You can send several identifiers in one conversion request. Tapfiliate uses exactly one, in this order:

1. `coupon`
2. `click_id`
3. `referral_code`
4. `asset_id` with `source_id`
5. `tracking_id`

If the winner can't be resolved, the request fails with `400`. Tapfiliate does not fall back to the next identifier. A `click_id` of another account, for example, fails with `Invalid click id` even when a valid `referral_code` is sent too.

One exception comes first: `customer_id` of an existing customer, in a program with recurring commissions, sends the conversion to that customer's affiliate.

## Choosing the program

The conversion never names a program. The identifier decides it:

* **`click_id` or `tracking_id`** — the program of the click.
* **`referral_code`** — an affiliate has a separate referral code in each program, so the code points to one program.
* **`coupon`** — the program the coupon is assigned to.

If your account uses program groups, send `program_group` with a `click_id` or `tracking_id`. Tapfiliate then accepts only clicks in that group's programs. With other identifiers `program_group` has no effect.

## Retries and duplicates

`external_id` is unique in your account. A second conversion with the same `external_id` fails with `400 Duplicate conversion. There is already a conversion for External id '…'`. That makes retries safe: treat this error as success.

A retry that arrives while an earlier attempt with the same `external_id` is still running, or within 10 seconds after one failed, gets `400 To many concurrent attempts to create conversion with id '…'` instead. Wait more than 10 seconds and retry.

Without `external_id` there is no duplicate check. Each retry, for example after a timeout, creates another conversion.

## Common pitfalls

* **Tracking the same sale twice.** The browser and the server share the duplicate check by `external_id`. If tapfiliate.js reports the sale with one ID and your server with another, for example the order ID and the payment ID, you get two conversions. This often happens with coupons: `tap('conversion')` with `coupons` and an API call with `coupon` for the same order. Track each sale in one place, or use the same `external_id` in both.
* **`Cookie expired`.** A conversion by `click_id` or `tracking_id` fails when the click is older than the program's cookie time. To track a late payment anyway, add `?override_max_cookie_time=true` to the request URL.
* **No identifier.** A request without `click_id`, `tracking_id`, `referral_code`, `coupon`, `asset_id` with `source_id` or `customer_id` fails with `Missing mandatory parameter(s)`.

More messages and what to do about them are in [Errors](/api-reference/errors#common-errors-when-tracking).


# JavaScript tracking
Source: https://developers.tapfiliate.com/tracking/javascript

Track clicks, customers and conversions from your website with tapfiliate.js.

tapfiliate.js detects visitors who come through affiliate links and reports their sign-ups and purchases. It only needs your account ID, which is public, so it is safe to use in the browser.

<Note>
  Using a shop or billing platform? Check the [integrations in the help center](https://support.tapfiliate.com) first: most of them set this up for you.
</Note>

## Setup

Add the snippet to **every page** of your site, so a click is recorded wherever the visitor lands:

```html theme={null}
<script src="https://script.tapfiliate.com/tapfiliate.js" type="text/javascript" async></script>
<script type="text/javascript">
  (function(t,a,p){t.TapfiliateObject=a;t[a]=t[a]||function(){
  (t[a].q=t[a].q||[]).push(arguments)}})(window,'tap');

  tap('create', 'YOUR_ACCOUNT_ID');
  tap('detect');
</script>
```

Then call `conversion`, `customer`, `trial` or `lead` on the page where the sale or sign-up happens. Calls are queued, so they work before the script has loaded.

These calls only reach Tapfiliate when the visitor came through an affiliate within the program's cookie time. For everyone else nothing is sent, so the code can stay on the page for all visitors.

## create

Initializes tapfiliate.js.

```js theme={null}
tap('create', accountId, options, callback);
```

| Argument | Type | Description |
| - | - | - |
| `accountId` | string, required | Your account ID. |
| `options` | object | Reserved, pass `{}`. |
| `callback` | function | Called once the tracking code is initialized. If the visitor already has a visitor ID, `tap.vids` is filled at this point. |

## detect

Looks for affiliate tracking parameters in the URL. If it finds them, it records a click and sets a cookie, so a later conversion is attributed to the affiliate. Without tracking parameters it makes no request.

```js theme={null}
tap('detect', options, callback);
```

| Option | Type | Description |
| - | - | - |
| `cookie_domain` | string | Domain to set the cookie on. Use your main domain when visitors land on one subdomain and convert on another. |
| `referral_code` | string | Referral code to use for this click instead of the one in the URL. |
| `referral_code_param` | string | Query parameter that carries the referral code instead of `ref`, for example `via` for links like `?via=janejameson`. |
| `always_callback` | boolean | Also call the callback when tracking fails. See [callbacks](#callbacks). |

```js theme={null}
tap('detect', { cookie_domain: 'example.com' });
```

## conversion

Tracks a conversion, usually a purchase. Put it on your thank-you page.

```js theme={null}
tap('conversion', externalId, amount, options, commissionType, callback);
```

| Argument | Type | Description |
| - | - | - |
| `externalId` | string | A unique ID for this conversion, such as your order ID. A second conversion with the same ID is not tracked, so reloading the thank-you page is safe. |
| `amount` | number | The order amount. Commissions are calculated from it. |
| `options` | object | See below. |
| `commissionType` | string | Identifier of the commission type to use, if your program has several. |
| `callback` | function | Called after the conversion is tracked. |

| Option | Type | Description |
| - | - | - |
| `customer_id` | string | Your ID of the customer. With recurring or lifetime commissions, the conversion goes to the affiliate who referred this customer. If the customer doesn't exist yet, it is created. |
| `currency` | string | Three-letter ISO currency code, if it differs from the program currency. |
| `coupons` | string or array | Coupon codes used in the order. A coupon linked to an affiliate wins over the cookie. |
| `meta_data` | object | Extra data to store with the conversion. Up to 10 properties, keys up to 64 and values up to 255 characters, without `" : { } ] \ ' / &`. Do not store personal data. |
| `program_group` | string | Program group to track to, for setups with several sites. |
| `always_callback` | boolean | Also call the callback when tracking fails. |

```js theme={null}
tap('conversion', 'ORD123', 49.99, {
  customer_id: 'USER1234',
  currency: 'EUR',
  meta_data: { plan: 'pro' },
});
```

## conversionMulti

Tracks one conversion with several commissions, for example a different rate per product category.

```js theme={null}
tap('conversionMulti', externalId, options, commissions, callback);
```

`options` is the same as for `conversion`. `commissions` is an array with one object per commission:

| Field | Type | Description |
| - | - | - |
| `sub_amount` | number | The part of the order amount for this commission. |
| `commission_type` | string | Identifier of the commission type. |

```js theme={null}
var commissions = order.lineItems.map(function (item) {
  return { sub_amount: item.subtotal, commission_type: item.category };
});

tap('conversionMulti', 'ORD123', {}, commissions);
```

## customer, trial and lead

Track a customer when a referred visitor signs up, before they pay. Conversions you track later for the same `customer_id` are attributed to the same affiliate.

```js theme={null}
tap('customer', customerId, options, callback);
tap('trial', customerId, options, callback);
tap('lead', customerId, options, callback);
```

`trial` and `lead` work like `customer` and set the customer's initial status to trial or lead. Use `trial` for SaaS and subscriptions, `lead` for lead generation and long sales cycles.

| Option | Type | Description |
| - | - | - |
| `coupons` | string or array | Coupon codes the customer used. A coupon linked to an affiliate wins over the cookie. |
| `meta_data` | object | Extra data to store with the customer, with the same limits as for conversions. |
| `always_callback` | boolean | Also call the callback when tracking fails. |

```js theme={null}
tap('trial', 'USER1234');
```

## click

<Warning>
  For standard setups use `detect`. `click` is for rare cases where you know the affiliate from your own data, for example a list of referring domains.
</Warning>

Records a click from tracking parameters you pass explicitly.

```js theme={null}
tap('click', trackingParameters, options, callback);
```

`trackingParameters` holds either a referral code or an asset ID and source ID, for example `{ referral_code: 'janejameson' }` or `{ asset_id: '1-abcdef', source_id: '2-cdefgh' }`. The only option is `always_callback`.

## Callbacks

By default the callbacks of `detect`, `conversion`, `conversionMulti`, `customer` and `click` fire only on success. Pass `always_callback: true` in the options to get every outcome, with the conventional signature:

```js theme={null}
tap('conversion', 'ORD123', 49.99, { always_callback: true }, null, function (error, result) {
  if (error) console.warn('Tapfiliate conversion was not tracked', error);
});
```

## Several sites

To track one program across several sites, create a program group per site, assign the program to it and pass the group in the conversion:

```js theme={null}
tap('conversion', 'ORD123', 49.99, { program_group: 'my-group' });
```


# Server-to-server tracking
Source: https://developers.tapfiliate.com/tracking/server-to-server

Track conversions and customers from your backend with postback requests.

Postbacks let your server report sales and sign-ups directly, without code in the browser. Use them when the purchase happens in your backend, in an app, or on a platform where you can't run tapfiliate.js.

Each postback is a single `GET` or `POST` request. Authenticate it with your API key in the `X-Api-Key` header, as described in [Authentication](/authentication).

| Action | Endpoint |
| - | - |
| Create a conversion | `https://api.tapfiliate.com/1.7/pb/con/c/` |
| Update a conversion | `https://api.tapfiliate.com/1.7/pb/con/u/` |
| Create a customer | `https://api.tapfiliate.com/1.7/pb/cus/c/` |
| Update a customer | `https://api.tapfiliate.com/1.7/pb/cus/u/` |

## Who referred the visitor

To attribute a conversion or customer, send one of these. If you send several, the first one in this list wins:

1. `coupon` — the affiliate's coupon code.
2. `click_id` — the click ID, if you stored it when the visitor arrived.
3. `referral_code` — the affiliate's referral code, the value of `ref=` in their link.
4. `asset_id` and `source_id` — from the affiliate's link.

## Create a conversion

<CodeGroup>
  ```bash POST theme={null}
  curl -X POST https://api.tapfiliate.com/1.7/pb/con/c/ \
    -H "X-Api-Key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "referral_code": "janejameson",
      "external_id": "ORD005",
      "amount": 100
    }'
  ```

  ```bash GET theme={null}
  curl "https://api.tapfiliate.com/1.7/pb/con/c/?referral_code=janejameson&external_id=ORD005&amount=100" \
    -H "X-Api-Key: YOUR_API_KEY"
  ```
</CodeGroup>

| Parameter | Description |
| - | - |
| `external_id` | Required. A unique ID for this conversion, such as your order ID. |
| `amount` | The conversion amount. Commissions are calculated from it. |
| `currency` | Three-letter ISO currency code. The program currency is used if omitted. |
| `customer_id` | Your ID of the customer. Used for recurring and lifetime commissions, depending on your program settings. |
| `meta_data` | Extra data to store with the conversion, as an object. |
| `user_agent` | The visitor's user agent, for statistics and fraud detection. |
| `ip` | The visitor's IP address, for fraud detection. |

A successful request returns `200` with the created conversion:

```json theme={null}
{
  "id": "cv_Ma5Z-kgUwHqoWUz9vE",
  "external_id": "ORD005",
  "amount": 100.0,
  "created_at": "2023-03-15T08:51:10+00:00",
  "program": { "id": "johns-affiliate-program", "title": "John's affiliate program", "currency": "USD" },
  "affiliate": { "id": "u_JaN3-J0n", "firstname": "Jane", "lastname": "Jameson" },
  "commissions": [
    { "id": "cm_FlC2mbDUM-o52U3NQj", "amount": 10.0, "currency": "USD", "commission_type": "standard", "approved": null }
  ]
}
```

## Update a conversion

Approve or disapprove a conversion, or correct its amount, by its `external_id`. Commission amounts are recalculated.

```bash theme={null}
curl -X POST https://api.tapfiliate.com/1.7/pb/con/u/ \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "ORD005",
    "status": "disapproved",
    "amount": 100
  }'
```

| Parameter | Description |
| - | - |
| `external_id` | Required. The ID of the conversion to update. |
| `status` | `approved` or `disapproved`. |
| `amount` | The new conversion amount. |
| `meta_data` | Extra data to store with the conversion. |

## Create a customer

Track a sign-up before the first payment. Later conversions with the same `customer_id` are attributed to the same affiliate.

```bash theme={null}
curl -X POST https://api.tapfiliate.com/1.7/pb/cus/c/ \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "referral_code": "janejameson",
    "customer_id": "USER1234",
    "status": "trial"
  }'
```

| Parameter | Description |
| - | - |
| `customer_id` | Required. Your ID of the customer, unique per customer. |
| `status` | Initial status: `new` (default), `trial` or `lead`. |
| `meta_data` | Extra data to store with the customer. |
| `user_agent` | The visitor's user agent. |
| `ip` | The visitor's IP address. |

## Update a customer

```bash theme={null}
curl -X POST https://api.tapfiliate.com/1.7/pb/cus/u/ \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "USER1234",
    "meta_data": { "plan": "pro" }
  }'
```

## Passing affiliate data through

Affiliates can add `tm_` parameters to their links, for example `?tm_foo=bar&tm_baz=qux`. To keep this data, read the parameters from the landing URL and send them as `meta_data`, here `{ "foo": "bar", "baz": "qux" }`.

<Note>
  Track a test conversion before you launch your program to check the whole flow.
</Note>