HarperDocumentation
Back to HomeDashboard
API ReferenceTracking API Reference

Tracking API Reference

Programmatically track clicks, conversions, and custom events

POST /track/click

Track a Facebook ad click. This endpoint captures the FBCLID and stores user information for attribution.

Request

POST https://api.harper.com/v1/track/click
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "fbclid": "IwAR1234567890abcdef",
  "storeId": "store_abc123",
  "landingPage": "https://mystore.com/products/item",
  "referrer": "https://facebook.com",
  "ipAddress": "192.168.1.1",
  "userAgent": "Mozilla/5.0 ...",
  "timestamp": "2026-01-31T06:00:00Z"
}

Parameters

ParameterTypeRequiredDescription
fbclidstringYesFacebook Click ID from the URL parameter
storeIdstringYesYour store identifier
landingPagestringYesFull URL where user landed
referrerstringNoHTTP referrer URL
ipAddressstringNoUser's IP address
userAgentstringNoUser's browser user agent

Response (200 OK)

{
  "success": true,
  "data": {
    "clickId": "click_abc123",
    "fbclid": "IwAR1234567890abcdef",
    "tracked": true,
    "timestamp": "2026-01-31T06:00:00Z"
  }
}

POST /track/conversion

Track a conversion event (purchase, signup, etc). The system will automatically match it to a click for attribution.

Request

POST https://api.harper.com/v1/track/conversion
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "storeId": "store_abc123",
  "eventType": "Purchase",
  "orderId": "ORDER_12345",
  "eventValue": 99.99,
  "currency": "USD",
  "customerData": {
    "email": "customer@example.com",
    "firstName": "John",
    "lastName": "Doe",
    "phone": "+1234567890",
    "city": "New York",
    "state": "NY",
    "country": "US",
    "zipCode": "10001"
  },
  "fingerprint": "fp_hash_abc123",
  "products": [
    {
      "productId": "prod_123",
      "name": "Product Name",
      "price": 99.99,
      "quantity": 1,
      "category": "Electronics"
    }
  ]
}

Response (200 OK)

{
  "success": true,
  "data": {
    "conversionId": "conv_abc123",
    "eventType": "Purchase",
    "attributed": true,
    "attributedTo": {
      "clickId": "click_abc123",
      "fbclid": "IwAR1234567890abcdef",
      "confidenceScore": 95
    },
    "capiSent": true,
    "timestamp": "2026-01-31T06:00:00Z"
  }
}

Code Examples

JavaScript / Node.js

const axios = require('axios');

// Track a click
const trackClick = async (fbclid, storeId) => {
  const response = await axios.post(
    'https://api.harper.com/v1/track/click',
    {
      fbclid: fbclid,
      storeId: storeId,
      landingPage: window.location.href,
      referrer: document.referrer,
      userAgent: navigator.userAgent
    },
    {
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
      }
    }
  );
  return response.data;
};

// Track a conversion
const trackConversion = async (orderId, value, customerEmail) => {
  const response = await axios.post(
    'https://api.harper.com/v1/track/conversion',
    {
      storeId: 'store_abc123',
      eventType: 'Purchase',
      orderId: orderId,
      eventValue: value,
      currency: 'USD',
      customerData: {
        email: customerEmail
      }
    },
    {
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
      }
    }
  );
  return response.data;
};

Python

import requests

API_KEY = 'YOUR_API_KEY'
BASE_URL = 'https://api.harper.com/v1'

def track_conversion(store_id, order_id, value, customer_email):
    headers = {
        'Authorization': f'Bearer {API_KEY}',
        'Content-Type': 'application/json'
    }
    
    payload = {
        'storeId': store_id,
        'eventType': 'Purchase',
        'orderId': order_id,
        'eventValue': value,
        'currency': 'USD',
        'customerData': {
            'email': customer_email
        }
    }
    
    response = requests.post(
        f'{BASE_URL}/track/conversion',
        json=payload,
        headers=headers
    )
    
    return response.json()

Common Error Codes

  • invalid_fbclid: The FBCLID parameter is invalid or expired
  • store_not_found: Store ID doesn't exist or is inactive
  • missing_required_field: Required parameter is missing
  • invalid_currency: Currency code must be ISO 4217 format (USD, EUR, etc)
  • rate_limit_exceeded: Too many requests, please slow down

Next

Next Article →

Was this helpful?