> ## Documentation Index
> Fetch the complete documentation index at: https://support.tapfiliate.com/llms.txt
> Use this file to discover all available pages before exploring further.
# How to setup postback for affiliates?
> Set up postback tracking using an affiliate subID
November 10, 2026
## Table of Contents
1. [What Is a Postback?](#h_077aeeaa52)
2. [Before You Start (Requirements)](#h_33d88ce48c)
3. [How Postbacks Work in Tapfiliate](#h_4e81c78493)
4. [Setting Up Tapfiliate Postbacks (Step-by-Step)](#h_d63264f881)
5. [Understanding Content Keys and SubIDs (Clear Example)](#h_be2c45b895)
6. [Pause or remove existing postback](#h_702d18a635)
7. [Testing Your Postback](#h_39733c225e)
8. [List of Available Macros (Quick Reference)](#h_ce6115b9e3)
9. [Common Mistakes & Best Practices](#h_525e8b1dbe)
## What Is a Postback?
A postback is a **server-to-server request** that Tapfiliate sends to an affiliate’s tracking system when a conversion is recorded. Unlike pixels or browser-based tracking, postbacks are:
* More reliable
* Not affected by ad blockers
* Commonly required by affiliate networks
## Before You Start (Requirements)
Before setting up a postback, make sure you have:
* The **postback URL** of your tracking system
* A list of the **parameters** your tracking system expects (for example: click ID, payout, currency)
* The name of the parameter in which **your tracking system expects the click ID** (e.g. `subid`, `subid1`, `click_id`)
**Important:** Only send the parameters your tracking system needs. Do **not** include personal or sensitive user data unless strictly required.
## How Postbacks Work in Tapfiliate
1. You send traffic using your Tapfiliate referral link.
2. A **SubID (click ID)** is passed in the link.
3. Tapfiliate stores this SubID.
4. When a conversion occurs, Tapfiliate fires a postback.
5. Your tracking system receives the SubID and matches the conversion to the original click.
## Setting Up Tapfiliate Postbacks
You set up postbacks yourself in your affiliate portal. The program owner can also create postbacks for you from their own dashboard.\
To set up a postback, follow these steps:\
**1. Open Postbacks** in the left menu of your affiliate portal.\
**2. Click the "Create new postback" button.** You need to be approved in at least one program to create a postback.\
**3. Enter a descriptive title** for your postback (e.g., "Sale").
**4. Choose the programs and sources** you want to receive data for. Leave a field empty to receive data for all of them.\
**5. Choose the event** (**Conversion** or **Customer**) and the **status**: **Create** to receive data when it is created, **Update** to receive data when it changes, or both.
**6. Choose the HTTP method:** GET sends the parameters in the query string, POST sends them in the request body.\
**7. Add the link to your server:**\
Paste the HTTPS postback URL of your tracking system.\
Example: [https://affiliate-network.com/postback](https://affiliate-network.com/postback)\
**8. Add Parameters:**\
For each parameter, enter the **Name** your tracking system expects and choose the Tapfiliate macro in **Content**. Click "+ Add one more" to add another parameter.\
Example (name = content):
```
clickid = ${click_subid}
payout = ${commission_amount}
currency = ${currency}
```
**Important:** Do not send unnecessary parameters. Only include what your tracking system requires.
**9. Test and save:** once all required fields are filled in, click **Test** in the "Test postback" block to send a test request and see your server's response. Then click the "Save" button.\
Once you have saved the postback, Tapfiliate will automatically send a request to your server whenever the chosen event happens. You can then use this data to track your earnings and measure the success of your promotional efforts.
## Understanding Content Keys and SubIDs (Clear Example)
This section clarifies one of the most commonly misunderstood concepts.
### Scenario
* You send traffic using this referral link:
[https://your-site.com/?ref=affiliate123\&tm\_subid1=ABC123](https://your-site.com/?ref=affiliate123\&tm_subid1=ABC123)
* Here, you are passing the **click ID** in `tm_subid1`.
***
### What Happens in Tapfiliate
* Tapfiliate stores the value `ABC123`.
* Internally, this value is available as the macro `${click_subid}`.
***
### What Is the Content Key?
The **content key** tells Tapfiliate **which SubID parameter name** should be sent back to you.\
In this example:
* You send the click ID in: `tm_subid1`
* Content key should be set to: `subid1`
***
### Resulting Postback
When the conversion happens, Tapfiliate sends:\
`subid1=ABC123`\
This allows your tracking system to correctly match the conversion to the original click.
## Receiving the external id
You can receive the external id of the conversion in your postback by using the \$\{conversion\_external\_id} macro. Example screenshot of how you can add the external id to the postback is given below:
## Pause or remove existing postbacks
Once you've created postbacks, you can edit, pause, or remove them as needed. Here's how:\
**1. Accessing the Postback Section:**
* Log in to your affiliate portal.
* Open **Postbacks** in the left menu.
**2. Viewing Existing Postbacks:**\
The **Postbacks** tab displays a list of all postbacks you've created. Each postback shows its title, link to server, programs, sources, event, status, HTTP method and parameters.\
**3. Editing a Postback:**
* Locate the postback you want to modify in the list.
* Click the edit (pencil) icon next to it.
* This opens the edit form, where you can change the title, programs, sources, event, status, HTTP method, link to server, or parameters.
* Once you've made the necessary edits, click the "Save" button to apply the changes.
**4. Pausing a Postback:**
* To temporarily disable a postback, locate it in the list.
* Click the activate/deactivate icon next to the postback. This will switch the postback to an inactive state.
* An inactive postback does not send any requests until you activate it again.
**5. Removing a Postback:**
* If you no longer need a particular postback, you can delete it permanently.
* Locate the postback you want to remove in the list.
* Click the trash can icon next to it.
* A confirmation dialog will appear. Click "Delete" to confirm the removal.
By following these steps, you can effectively manage your postbacks in Tapfiliate.
## Testing Tapfiliate Postbacks
It's important to properly manage and test your Tapfiliate postbacks to ensure they are functioning correctly. Here are some tips:
* **Test your postbacks:** Before launching your affiliate campaign, it's essential to test your postbacks to make sure they are sending data correctly. You can do this with the **Test** button in the "Test postback" block of the postback form: it sends a test request to your server and shows the response.
## List of Available Macros (Quick Reference)
Here is the full list of macros you can use in a Tapfiliate postback. Dates are sent in ISO 8601 format (for example `2026-11-04T17:19:36+00:00`) in the time zone set in your account. Amounts are sent as a number with two decimals and no currency symbol (for example `49.90`).
| Macro | Description |
| - | - |
| `${click_subid}` | Affiliate click ID (SubID). Set the content key to choose which SubID is sent (see the section above). Without a content key, all SubIDs of the click are sent as JSON. |
| `${click_id}` | Tapfiliate ID of the click. Empty if the conversion is not linked to a click. |
| `${click_time}` | Date and time of the click. Empty if the conversion is not linked to a click. |
| `${click_referrer}` | Referrer of the click. Empty if the conversion is not linked to a click. |
| `${conversion_id}` | Unique conversion ID |
| `${conversion_amount}` | Conversion amount as sent by the advertiser, for example `49.90`. If the advertiser sends a conversion without an amount, the value is `0.00`. Use `${conversion_currency}` for the currency. |
| `${commission_amount}` | Approved commission of this affiliate for the conversion. MLM commissions of upline affiliates are not included. Commissions that are not approved yet are not included either. |
| `${conversion_created_at}` | Date and time the conversion was created |
| `${conversion_time}` | Number of seconds between the click and the conversion. Empty if the conversion is not linked to a click. |
| `${conversion_external_id}` | External ID of the conversion |
| `${conversion_status}` | Status of the conversion |
| `${conversion_currency}` | Currency code of the conversion. Empty if the conversion has no currency. |
| `${conversion_meta_data}` | Meta data of the conversion. Set the content key to send a single value (for example `tm_subid1`). Without a content key, all meta data is sent as JSON. |
| `${customer_id}` | ID of the customer. Empty if the conversion has no customer. |
| `${customer_created_at}` | Date and time the customer was created |
| `${customer_status}` | Status of the customer |
| `${customer_meta_data}` | Meta data of the customer. Set the content key to send a single value. Without a content key, all meta data is sent as JSON. |
| `${currency}` | Currency of the program |
| `${program_id}` | Program ID |
| `${program_title}` | Title of the program |
Conversion macros are empty in postbacks for customer events. Always check which parameters your tracking system expects.
## Troubleshooting and best practices
Scenario: An affiliate sets up their Tapfiliate account and configures a postback using a click sub‑ID (via `tm_subid1`‑`tm_subid10`) in their referral links. However, when a conversion occurs, they never receive their click ID back in the postback payload—breaking the tracking.\
\
**Cause:**\
The advertiser might be using Tapfiliate’s REST API for click and conversion tracking—but they only might be sending basic data when creating a click (e.g., `referral_code`), **not storing or forwarding the affiliate’s sub‑ID metadata** (like click\_id) in the conversion API call. Because of these reasons, Tapfiliate cannot include that sub-ID in the postback (using `${click_subid}`), so it never reaches the affiliate.\
\
**Resolution:**\
Reach out to the advertiser to make sure their REST integration carries forward the affiliate sub‑ID metadata from the click through to the conversion call:
1. **When creating the click**, the advertisers must include the affiliate’s sub-id metadata: (example body)
```json theme={null}
{ "referral_code": "AFFCODE", "meta_data": { "sub_id": "AFFCLICK" }}
```
2. **Store the click ID and metadata** in a cookie or session so it’s available at conversion time.
3. **When sending the conversion**, include the same metadata.
## Common Mistakes & Best Practices
### Common Mistakes
* Sending unnecessary or sensitive data
* Using HTTP instead of HTTPS
* Incorrect SubID/content key mapping
* Not testing the postback
### Best Practices
* Always use HTTPS endpoints
* Send **only required parameters**
* Clearly document SubID usage with affiliates
### Still Need Help?
If you have questions or run into issues, contact us at [support@tapfiliate.com](mailto:support@tapfiliate.com). Our team is happy to help.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.