Server-to-Server Integration: Order (Conversion) Tracking

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 order from your site or app. The call is server-to-server (S2S) but should forward the end user’s browser context (e.g., User-Agent) so attribution remains accurate.  If you haven't previously completed the click tracking, you will also need to implement Server-to-Server Integration: Click Tracking to complete the integration.

When to Call

Call the order API once for every order at the moment the order is paid/confirmed:

• Traditional carts: on the server handling the order confirmation (“thank-you”) after payment is captured.

• Headless/APP: as part of your order service once status transitions to “paid/complete.”

• Retries: safe if you reuse the same order_number.

Endpoint

• HTTP Method: POST

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

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

{
  "current_url": "http://google.com",
  "tracking_ids": {
    "user_id": [""],
    "visitor_id": [""],
    "avantlink_avad": ""
  },
  "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36",
  "user_ip_address": "127.0.0.1",
  "referrer_url": "https://google.com",
  "google_click_id": "",
  "custom_tracking_code": "",
  "order": {
    "order_number": "12345",
    "order_amount_subtotal": 100.00,
    "currency": "USD",
    "coupon_codes": ["free-shipping"],
    "customer": {
      "new_customer": false,
      "country": "USA",
      "region": "",
      "state": "UT"
    },
    "products": [
      {
        "product_sku": "1234",
        "product_amount": 50.00,
        "quantity": "1"
      }
    ]
  }
}

Field Reference & Formatting

The following fields are required.

Product Array

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.

Example Requests
 

CURL

curl -X POST "https://client.avantlink.com/merchants/{{merchant_id}}/tracking/order" \
  -H "Content-Type: application/json" -H "Accept: application/json" \
  -d '{
    "current_url": "https://store.example.com/checkout/thank_you?o=asdf",
    "tracking_ids": {
      "user_id": ["123456"],
      "visitor_id": ["vis_3f2c1a97"],
      "avantlink_avad": "77_f3afbe121"
    },
    "user_agent": "Mozilla/5.0 ...",
    "user_ip_address": "203.0.113.45",
    "referrer_url": "https://store.example.com/checkout",
    "order": {
      "order_number": "12345",
      "order_amount_subtotal": "100.00",
      "currency": "USD",
      "coupon_codes": ["free-shipping"],
      "customer": { "new_customer": false, "country": "US", "region": "", "state": "UT" },
      "products": [
        { "product_sku": "1234", "product_amount": "50.00", "quantity": "2" }
      ]
    }
  }'

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']}",
  "order" => [
    "order_number" => "1234",
    "order_amount_subtotal" => 10.00,
    "currency" => "USD",
    "coupon_codes" => [],
    "customer" => [
      "new_customer" => false,
      "country" => "USA",
      "region" => "",
      "state" => "UT",
    ],
    "products" => [
      [
        "product_sku" => "123451",
        "product_amount" => 10.00,
        "quantity" => 1
      ]
    ]
  ]                 
];


$ch = curl_init("https://client.avantlink.com/merchants/".$merchant_id."/tracking/order");
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.