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

This integration uses a combination of javascript and the REST API for tracking Customers and/or Conversions.

  1. Place the following code in the <head> of every page you want affiliates to refer traffic to (all landing pages).

    <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>
    

    {{{{NO_ACCOUNT_ID_SET_MESSAGE}}}}

  2. The following code allows you to fetch the current tracking id for the visitor. For privacy reasons this id will change each time the visitor visits your site through an affiliate link. The id links the visitor to the last referring affiliate. We advice you to grab the tracking id just before you want to track a Conversion or Customer.

    <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('getTrackingId', null, function(trackingId) {
        // Send tracking id to your backend and persist it
      });
    </script>
    

    {{{{NO_ACCOUNT_ID_SET_MESSAGE}}}}

The tracking id is passed back as the first parameter of the callback. It will be either a string, or null in case no tracking id exists for the current visitor.

  1. Next use the tracking 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 '
        {
            "tracking_id": "XXXXX-XXX-XXXX-XXXX-XXXXX",
            "external_id": "ORDER001",
            "amount": 10
        }'
    
    • [[[[tracking_id]]]] This is the string obtained in step 2.
    • [[[[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.

    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 '
        {
            "tracking_id": "XXXXX-XXX-XXXX-XXXX-XXXXX",
            "customer_id": "USER001",
            "status": "trial"
        }'
    
    • [[[[tracking_id]]]] This is the string obtained in step 2.
    • [[[[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


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.

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.

Start a 14-day free trial with all our features enabled

Start now