Skip to main content

Server-to-Server Integration: Click Tracking

Updated

Overview

AvantLink's server-to-server tracking has several advantages and uses two different endpoints to track clicks and sales.  Use this endpoint to record an affiliate/referral click from your site or app on behalf of a specific merchant.  The call is server-to-server (S2S) but should forward the end user’s browser context (e.g., User-Agent) so attribution remains accurate. After completing this you will need to implement Server-to-Server Integration: Order (Conversion) Tracking to complete the integration.

Endpoint

  • HTTP Method: POST

  • URL Template:
    https://client.avantlink.com/merchants/{merchant_id}/tracking/click

  • Path Parameter:

    • merchant_id (UUID): Your AvantLink Merchant UUID ID.

Required Headers

  • Content-Type: application/json

  • Accept: application/json

  • User-Agent: <your-server-identifier> (your server’s User Agent)

  • Forwarded client header (recommended):
    Also include the end user’s browser UA in the JSON body’s user_agent field (see below). If you also forward IPs via a future endpoint, be sure to respect privacy laws

 

Request Body (JSON)

Below is an example of the payload.

{
  "tracking_ids": {
    "user_id": [],
    "visitor_id": [],
    "avantlink_avad": ""
  },
  "user_agent": "",
  "current_url": "",
  "referrer_url": "",
  "google_click_id": "",
  "custom_tracking_code": "",
  "user_ip_address": ""
}

 

Required Field Reference

The following fields are required.

Field Type Description
user_id array of strings One or more internal user identifiers associated with the click session. If you have a single user ID, send an array with one element. If the user is anonymous, you need to send a visitor_id instead. 
visitor_id array of strings Your anonymous visitor/session/cart identifier.
avantlink_avad string The AvantLink click token (AVAD) captured from the incoming referral (e.g., query param). Send exactly as received. This MUST be provided if you received it.
user_agent string The end user’s browser User-Agent string captured from the original client request (HTTP_USER_AGENT).
current_url string The full URL on your site where the click occurred (scheme, host, path, and query).

 

Optional Field Reference

The following fields are not required but highly suggested to be provided if you have the information. The more information that is provided the better your tracking will be.

Field Type Description
user_ip_address string The end users ip address NOT the servers ip address. 
referrer_url string The browsers referrer url.
google_click_id string The google click id. 
custom_tracking_code string Any custom tracking code you would like to provide.

 

When to Call

The click endpoint will need to be called when the user first lands on your website and provided an avad param. You can also call it on every page hit if you would like for more in depth tracking.

 

Example Requests
 

CURL

curl -X POST "https://client.avantlink.com/merchants/{{merchant_id}}/tracking/click" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "tracking_ids": {
      "user_id": ["u_78901"],
      "visitor_id": ["vis_3f2c1a97"],
      "avantlink_avad": "77_f3afbe121"
    },
    "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)...",
    "current_url": "https://store.example.com/products/widget?avad=77_f3afbe121"
  }

 

PHP

$merchant_id = ''; //INSERT your merchant uuid id here. 
$payload = [
  "tracking_ids" => [
    "user_id" => ["123456"],
    "visitor_id" => ["vis_3f2c1a97"],
    "avantlink_avad" => "77_f3afbe121"
  ],
  "user_agent" => $_SERVER['HTTP_USER_AGENT'] ?? "",
  "current_url" => (isset($_SERVER['HTTPS']) ? "https" : "http") .
                   "://{$_SERVER['HTTP_HOST']}{$_SERVER['REQUEST_URI']}"
];

$ch = curl_init("https://client.avantlink.com/merchants/".$merchant_id."/tracking/click");
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => ["Content-Type: application/json", "Accept: application/json"],
  CURLOPT_POSTFIELDS => json_encode($payload),
  CURLOPT_RETURNTRANSFER => true
]);
$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

 

Example Response

 

200 OK

{
  "success": true
}

 

400 Bad Request

{
  "error": "You must provide at least one tracking id in order to generate a episode_id.",
  "error_key": "client.model.merchants_tracking.tracking_ids.blank",
  "exception": "InvalidArgumentException"
}

 

Privacy & Security

  • Do not send Personal Information (names, emails, phone numbers) in any field. If you must use a users email address as an identifier make sure to hash it first

  • Treat avantlink_avad as an opaque token; do not modify.

  • Comply with applicable laws (GDPR/CCPA). Provide disclosure/consent for tracking where required.

 

 

 

 

 

 

 

Related articles