- Conversion tracking
- Commission based on order amount
- Track affiliate coupon code conversions
- Supports lifetime commissions
- Per category commissions
- Track order currency
- Auto-handle recurring commissions
- Auto-handle refunds and disputes
The current version of the Postback is V1.7.
Authentication
Authentication with the Tapfiliate API is achieved by sending your X-Api-Key along in the header of every request:
X-Api-Key: “YOUR_API_KEY”
You can find and manage your Api Key in your account settings.
Create a conversion
To create a conversion, you need to send a POST or GET request to the Tapfiliate server. Code Example:
curl -X GET -H 'X-Api-Key: YOUR API KEY HERE' https://api.tapfiliate.com/1.7/pb/con/c/?referral_code=nwjinmy&amount=100&external_id=ORD005
or
curl -X POST -H 'Content-Type: application/json' -H 'X-Api-Key: YOUR API KEY HERE' https://api.tapfiliate.com/1.7/pb/con/c/ -d '
{
"referral_code": "nwjinmy",
"amount": "100",
"external_id": "ORD005"
}'
Required parameters:
1. [[[[external id]]]] A unique id for this conversion. It can be anything that is meaningful to you, like an order number, user id, email address etc. This id has to be unique for every conversion.
2. You have to also send one of the parameters:
• [[[[referral code]]]] An affiliate’s referral code. This corresponds to the value of ref= in their referral link
• [[[[coupon]]]] The affiliate’s coupon code.
• [[[[click id]]]] The click id. Used to add additional reporting information.
• [[[[asset id]]]] and [[[[source id]]]] A source id or an asset id.
If more than one of them is sent, then one will be used, according to priority (from highest to lowest): coupon, click_id, referral_code, asset_id and source_id.
If necessary, you can add additional parameters to the request:
• [[[[amount]]]] The conversion amount (number).
• [[[[currency]]]] The three letter ISO currency code.If not passed, the default program currency will be used.
• [[[[customer id]]]] The id for this customer in your system. The customer id should be unique for each customer. Depending on your program settings, this can be used for recurring / lifetime commissions. You can read more about this here.
• [[[[meta data]]]] Additional data for the conversion (object). Affiliates can use meta data to send additional data about their traffic. If you want to use this feature for your affiliates, check the url for any ?tm_{key-goes-here}= query parameters. They can be sent as an object when creating a conversion. For example, https://some-site.com/?tm_foo=bar&tm_baz=qux contains two meta data objects: foo=bar and baz=qux.
• [[[[user agent]]]] The client’s user agent string. Used for statistics and fraud detection.
• [[[[ip]]]] The client’s ip. Used for fraud detection.
If the request to create a conversion is successfully processed, a response with a 200 code will be returned. The response body will be a JSON object with information about the created conversion, for example:
{ "id": "cv_Ma5Z-kgUwHqoWUz9vE", "created_at": "2023-03-15T08:51:10+00:00", "click": null, "affiliate_meta_data": null, "program": { "id": "johns-affiliate-program", "title": "John's affiliate program", "currency": "USD" }, "affiliate": { "id": "u_JaN3-J0n", "firstname": "Jane", "lastname": "Jameson" }, "warnings": null, "amount": 100.0, "meta_data": { "testmeta": "testmetavalue" }, "customer": null, "external_id": "test", "commissions": [ { "kind": "regular", "affiliate": { "id": "u_JaN3-J0n", "firstname": "Jane", "lastname": "Jameson" }, "currency": "USD", "id": "cm_FlC2mbDUM-o52U3NQj", "created_at": "2023-03-15T08:51:10+00:00", "payout": null, "commission_type": "standard", "approved": null, "amount": 10.0, "comment": null, "conversion_sub_amount": 100.0, "final": null } ] }
Update a Conversion
To update a conversion, you must send a POST or GET request to the Tapfiliate server. Code Example:
curl -X GET -H 'X-Api-Key: YOUR API KEY HERE' https://api.tapfiliate.com/1.7/pb/con/u/?amount=100&external_id=ORD345&meta_data[testparam]=testvalue&status=disapproved
or
curl -X POST -H 'Content-Type: application/json' -H 'X-Api-Key: YOUR API KEY HERE' https://api.tapfiliate.com/1.7/pb/con/u/ -d '
{
"external_id": "ORD005",
"status": "disapproved",
"amount": "100",
"meta_data": {
"testparam": "testvalue"
}
}'
Required parameters:
• [[[[external id]]]] A unique id for this conversion.
Parameters for changing the conversion:
• [[[[status]]]] Conversion commission status. It can have two meanings:approved/disapproved.
• [[[[amount]]]] The amount of the conversion (number). Commission amounts will be automatically recalculated.
• [[[[meta data]]]] Additional data for the conversion (object). Affiliates can use meta data to send additional data about their traffic. If you want to use this feature for your affiliates, check the url for any ?tm_{key-goes-here}= query parameters. They can be sent as an object when creating a conversion. For example, https://some-site.com/?tm_foo=bar&tm_baz=qux contains two meta data objects: foo=bar and baz=qux.
If the request to create a conversion is successfully processed, a response with a 200 code will be returned.
Create a Customer
To create a customer, you must send a POST or GET request to the Tapfiliate server. Code Example:
curl -X GET -H 'X-Api-Key: YOUR API KEY HERE' https://api.tapfiliate.com/1.7/pb/cus/c/?referral_code=nwjinmy&customer_id=test
or
curl -X POST -H 'Content-Type: application/json' -H 'X-Api-Key: YOUR API KEY HERE' https://api.tapfiliate.com/1.7/pb/cus/c/ -d '
{
"referral_code": "nwjinmy",
"customer_id": "test"
}'
Required parameters:
1. [[[[customer id]]]] The id for this customer in your system. The customer id should be unique for each customer. Depending on your program settings, this can be used for recurring / lifetime commissions. You can read more about this here.
2. You have to also send one of the parameters:
• [[[[referral code]]]] An affiliate’s referral code. This corresponds to the value of ref= in their referral link
• [[[[coupon]]]] The affiliate’s coupon code.
• [[[[click id]]]] The click id. Used to add additional reporting information.
• [[[[asset id]]]] and [[[[source id]]]] A source id or an asset id.
If more than one of them is sent, then one will be used, according to priority (from highest to lowest): coupon, click_id, referral_code, asset_id and source_id.
If necessary, you can add additional parameters to the request:
• [[[[meta data]]]] Additional data for the conversion (object). Affiliates can use meta data to send additional data about their traffic. If you want to use this feature for your affiliates, check the url for any ?tm_{key-goes-here}= query parameters. They can be sent as an object when creating a conversion. For example, https://some-site.com/?tm_foo=bar&tm_baz=qux contains two meta data objects: foo=bar and baz=qux.
• [[[[user agent]]]] The client’s user agent string. Used for statistics and fraud detection.
• [[[[ip]]]] The client’s ip. Used for fraud detection.
• [[[[status]]]] Defines the initial status of the customer. Possible values: new, trial, lead. The default is new if not passed. You can read more here.
If the request to create a customer is successfully processed, a response with a 200 code will be returned. The response body will be a JSON object with information about the created customer, for example:
{ "id": "cu_wSsch4qEquiSIW4hTF", "created_at": "2023-03-15T11:03:21+00:00", "click": null, "affiliate_meta_data": null, "program": { "id": "johns-affiliate-program", "title": "John's affiliate program", "currency": "USD" }, "affiliate": { "id": "u_JaN3-J0n", "firstname": "Jane", "lastname": "Jameson" }, "warnings": null, "meta_data": { "testmeta": "testmetavalue" }, "customer_id": "Testtesttest111", "status": "new" }
Update a Customer
To update a customer, you must send a POST or GET request to the Tapfiliate server. Code Example:
curl -X GET -H 'X-Api-Key: YOUR API KEY HERE' https://api.tapfiliate.com/1.7/pb/cus/u/?customer_id=test&meta_data[testparam]=testvalue
or
curl -X POST -H 'Content-Type: application/json' -H 'X-Api-Key: YOUR API KEY HERE' hhttps://api.tapfiliate.com/1.7/pb/cus/u/ -d '
{
"customer_id": "test",
"meta_data": {
"testparam": "testvalue"
}
}'
Required parameters:
• [[[[customer id]]]] The unique identifier of the customer.
Parameters for changing the customer:
• [[[[meta data]]]] Additional data for the conversion (object). Affiliates can use meta data to send additional data about their traffic. If you want to use this feature for your affiliates, check the url for any ?tm_{key-goes-here}= query parameters. They can be sent as an object when creating a conversion. For example, https://some-site.com/?tm_foo=bar&tm_baz=qux contains two meta data objects: foo=bar and baz=qux.
If the conversion change request is successfully processed, a 200 response will be returned.
There’s an option for users who need to implement the Postback integration on a CMS or PHP. Follow the links below to check guides for deeper integrations.
Postback instruction for a CMS
Important
Please remember to test a conversion before starting your program. This way you can verify that tracking has been set up correctly. You can create a test conversion by following the steps described here.
