Integrating with REST API

Out-of-the-box features:

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

If you don’t want to use any javascript, you can follow these steps to set up a REST-only integration.

For any page visit, check the URL for the presence of the ?ref= query parameter. If it is present, get the value and create a click:
```
curl -X POST -H 'Content-Type: application/json' -H 'Api-Key: ((((YOUR API KEY HERE))))' https://api.tapfiliate.com/1.6/clicks/ -d '
    {
        "referral_code": "ref-value-goes-here"
    }'
```
The response will be a JSON Object with one property id, which is the Click id. Persist this value in a cookie with a lifetime equal than or greater than the cookie time you configured in your account.
This is the minimal number of arguments needed. We do however advise passing additional information.
Next use the click id to create a Customer or a Conversion through the API. For one-off purchases (E-Commerce), you will likely want to track a Conversion. For SaaS, Subscription or Lead-gen, you will most likely want to track a Customer. You can read more about the difference between Customers and Conversions in this article.
Tracking a Conversion can be done as follows:
```
curl -X POST -H 'Content-Type: application/json' -H 'Api-Key: ((((YOUR API KEY HERE))))' https://api.tapfiliate.com/1.6/conversions/ -d '
    {
        "click_id": "XXXX-XXXX-XXXX-XXXX-XXXXX",
        "external_id": "ORDER001",
        "amount": 10
    }'
```
- [[[[click_id]]]] This is the string obtained in step 1.
- [[[[external_id]]]] is a unique id that should be generated on your end. It can be anything that is meaningful to you, like an order number, transaction id or similar. The external id has to be unique for each conversion.
- [[[[amount]]]] is the total value of the conversion. The commission will be calculated based on this amount.
This is the minimal number of arguments needed. We do however advice passing additional information.
Tracking a Customer can be done in the following way:
```
curl -X POST -H 'Content-Type: application/json' -H 'Api-Key: ((((YOUR API KEY HERE))))' https://api.tapfiliate.com/1.6/customers/ -d '
    {
        "click_id": "XXXX-XXXX-XXXX-XXXX-XXXXX",
        "customer_id": "USER001",
        "status": "trial"
    }'
```
- [[[[click_id]]]] This is the string obtained in step 1.
- [[[[customer_id]]]] is the id for this customer in your system. The customer id should be unique for each customer.
- [[[[status]]]] One of “trial” (SaaS / Subscription), “lead” (Lead-gen) or “new” (E-Commerce / Generic). You can read more about customer statuses and their implications in this article
This is the minimal number of arguments needed. We do however advice passing additional information.

Recurring / Lifetime

For recurring / lifetime commissions, you can track a Customer first. Then, on each payment, you can create a Conversion for the Customer as follows

curl -X POST -H 'Content-Type: application/json' -H 'Api-Key: ((((YOUR API KEY HERE))))' https://api.tapfiliate.com/1.6/conversions/ -d '
    {
        "customer_id": "USER001",
        "external_id": "ORDER001",
        "amount": 10
    }'

This conversion will be automatically attributed to the original referring affiliate for the customer.

Important: Please make sure to enable Recurring / Lifetime in your program setting. You can see all available attributes for tracking conversions in the REST API docs.

Passing additional data when tracking clicks

We recommend sending the following additional data when tracking a click.

curl -X POST -H 'Content-Type: application/json' -H 'Api-Key: ((((YOUR API KEY HERE))))' https://api.tapfiliate.com/1.6/clicks/ -d '
    {
        "referral_code": "johndoe",
        "source_id": "123-abc",
        "meta_data": {
            "foo": "bar"
        },
        "referrer": "https://their-site.com",
        "landing_page": "https://my-site.com",
        "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/81.0.4044.129 Safari/537.36"
    }'

[[[[Source id]]]] Affiliates can use “sources” to label traffic. If you want to enable this feature for your affiliates, inspect the url for the presence of the ?tap_s= query parameter and pass its value (if any) as the source_id when tracking the click.
[[[[Meta data]]]] Affiliates can use “meta data” to send extra data with their traffic. If you want to enable this feature for your affiliates, inspect the url for the presence of any ?tm_{key-goes-here}= query parameters. These can be sent as an object when tracking the click. E.g. the url https://some-site.com/?tm_foo=bar&tm_baz=qux, contains two meta data pairs: foo=bar and baz=qux.
[[[[Referrer]]]] The HTTP referrer (if any). Will be used in reporting.
[[[[Landing page]]]] The url of the current page. Will be used in reporting.
[[[[User agent]]]] The full user agent of the visitor.

Passing additional data when tracking conversions

We recommend sending the following additional data when tracking a conversion.

curl -X POST -H 'Content-Type: application/json' -H 'Api-Key: ((((YOUR API KEY HERE))))' https://api.tapfiliate.com/1.6/conversions/ -d '
    {
        "click_id": "XXXXX-XXX-XXXX-XXXX-XXXXX",
        "external_id": "ORDER001",
        "amount": 10,
        "customer_id": "USER001",
        "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/81.0.4044.129 Safari/537.36",
        "ip": "111.11.11.111"
    }'

[[[[customer_id]]]] is the id for this customer in your system. The customer id should be unique for each customer.
[[[[User agent]]]] The full user agent of the visitor.
[[[[Ip]]]] The ip address of the visitor. Will be used for fraud detection.

Passing additional data when tracking customers

We recommend sending the following additional data when tracking a customer.

curl -X POST -H 'Content-Type: application/json' -H 'Api-Key: ((((YOUR API KEY HERE))))' https://api.tapfiliate.com/1.6/customers/ -d '
    {
        "click_id": "XXXXX-XXX-XXXX-XXXX-XXXXX",
        "customer_id": "USER001",
        "status": "trial",
        "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/81.0.4044.129 Safari/537.36",
        "ip": "111.11.11.111"
    }'

[[[[User agent]]]] The full user agent of the visitor.
[[[[Ip]]]] The ip address of the visitor. Will be used for fraud detection.

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.