AxiTrace HTTP Ingestion API reference - send server-side events directly to AxiTrace from any backend language.

HTTP API

Send events directly from your server using our REST API. Perfect for backend integrations, webhooks, and server-side tracking where the JavaScript SDK isn't available.

Base URL

All server-side API requests should be made to:

https://stat.axitrace.com
Server-Side vs Client-Side

Server-side requests always use stat.axitrace.com with your Secret Key.
Client-side (JavaScript SDK) requests use your custom tracking domain (e.g., axi.yourdomain.com) with your Public Key.

Authentication

Server-side requests use HTTP Basic Authentication with your Secret Key. Use the Secret Key as the username and leave the password empty.

# Note the colon after the secret key (empty password)
curl -u "sk_live_YOUR_SECRET_KEY:"
Keep Your Secret Key Safe

Never expose your Secret Key in client-side code, mobile apps, or public repositories. See the Authentication guide for security best practices.

Request Format

All requests must include:

  • Content-Type: application/json header
  • User-Agent header (required for server-side requests)
  • JSON body with event data

API Endpoints

Page View

POST /v1/page/view

Track when a user views a page.

Required Shape: label + client + params

label and client (with at least one identifier: customId, id, uuid, or email) are always required. Event-specific fields go inside params, not at the top level.

curl -X POST https://stat.axitrace.com/v1/page/view \
  -u "sk_live_YOUR_SECRET_KEY:" \
  -H "Content-Type: application/json" \
  -H "User-Agent: MyApp/1.0" \
  -d '{
    "label": "Products Page",
    "client": {
        "customId": "user-123"
    },
    "params": {
        "url": "https://example.com/products",
        "title": "Products Page",
        "referrer": "https://google.com"
    }
  }'
Field Required Notes
label Required Not persisted, but the request 400s without it
client Required At least one of customId, id, uuid, email
params.url Required Must start with http:// or https://
sessionId, eventSalt Optional Top-level fields, not inside params

Product View

POST /v1/product/view

Track when a user views a product.

curl -X POST https://stat.axitrace.com/v1/product/view \
  -u "sk_live_YOUR_SECRET_KEY:" \
  -H "Content-Type: application/json" \
  -H "User-Agent: MyApp/1.0" \
  -d '{
    "label": "Premium Widget",
    "client": {
        "customId": "user-123"
    },
    "params": {
        "sku": "PROD-001",
        "price": 99.99,
        "currency": "USD",
        "category": "Electronics"
    }
  }'
Field Required Notes
label, client Required Same rules as Page View above
params.sku Required Non-empty string
params.price Optional Number, must be >= 0 if present
params.currency Optional Non-empty string if present

Add to Cart

POST /v1/product/addToCart

Track when a user adds a product to their cart.

curl -X POST https://stat.axitrace.com/v1/product/addToCart \
  -u "sk_live_YOUR_SECRET_KEY:" \
  -H "Content-Type: application/json" \
  -H "User-Agent: MyApp/1.0" \
  -d '{
    "label": "Premium Widget",
    "client": {
        "customId": "user-123"
    },
    "params": {
        "sku": "PROD-001",
        "quantity": 2,
        "finalUnitPrice": {
            "amount": 99.99,
            "currency": "USD"
        }
    }
  }'
Field Required Notes
label, client Required Same rules as Page View above
params.sku Required Non-empty string
params.quantity Optional Number, must be > 0 if present
params.finalUnitPrice, regularUnitPrice, discountedUnitPrice Optional Money objects ({amount, currency}), not scalar prices

View Item List

POST /v1/catalog/view_list

Track when a user views a category, collection or search-results listing.

curl -X POST https://stat.axitrace.com/v1/catalog/view_list \
  -u "sk_live_YOUR_SECRET_KEY:" \
  -H "Content-Type: application/json" \
  -H "User-Agent: MyApp/1.0" \
  -d '{
    "client_id": "user-123",
    "item_list_id": "category_widgets",
    "item_list_name": "Widgets",
    "items": [
      { "item_id": "PROD-001", "item_name": "Premium Widget", "price": 99.99 },
      { "item_id": "PROD-002", "item_name": "Standard Widget", "price": 49.99 }
    ]
  }'

Select Item

POST /v1/catalog/select_item

Track when a user clicks a product in a listing. items must contain exactly one entry - the product that was clicked - and item_list_id is what links the click back to the /v1/catalog/view_list impression it came from.

curl -X POST https://stat.axitrace.com/v1/catalog/select_item \
  -u "sk_live_YOUR_SECRET_KEY:" \
  -H "Content-Type: application/json" \
  -H "User-Agent: MyApp/1.0" \
  -d '{
    "client_id": "user-123",
    "item_list_id": "category_widgets",
    "item_list_name": "Widgets",
    "items": [
      { "item_id": "PROD-001", "item_name": "Premium Widget", "price": 99.99, "position": 1 }
    ]
  }'

Remove from Cart

POST /v1/cart/remove

Track when a user removes an item from their cart.

curl -X POST https://stat.axitrace.com/v1/cart/remove \
  -u "sk_live_YOUR_SECRET_KEY:" \
  -H "Content-Type: application/json" \
  -H "User-Agent: MyApp/1.0" \
  -d '{
    "client_id": "user-123",
    "currency": "USD",
    "value": 99.99,
    "items": [
      {
        "item_id": "PROD-001",
        "item_name": "Premium Widget",
        "price": 99.99,
        "quantity": 1
      }
    ]
  }'

Begin Checkout

POST /v1/checkout/begin

Track when a user starts the checkout process.

curl -X POST https://stat.axitrace.com/v1/checkout/begin \
  -u "sk_live_YOUR_SECRET_KEY:" \
  -H "Content-Type: application/json" \
  -H "User-Agent: MyApp/1.0" \
  -d '{
    "client_id": "user-123",
    "currency": "USD",
    "value": 199.98,
    "items": [
      {
        "item_id": "PROD-001",
        "item_name": "Premium Widget",
        "price": 99.99,
        "quantity": 2
      }
    ]
  }'

Add Shipping Info

POST /v1/checkout/add_shipping_info

Track when a user adds shipping information during checkout.

curl -X POST https://stat.axitrace.com/v1/checkout/add_shipping_info \
  -u "sk_live_YOUR_SECRET_KEY:" \
  -H "Content-Type: application/json" \
  -H "User-Agent: MyApp/1.0" \
  -d '{
    "client_id": "user-123",
    "currency": "USD",
    "value": 199.98,
    "shipping_tier": "Express",
    "items": [
      {
        "item_id": "PROD-001",
        "item_name": "Premium Widget",
        "price": 99.99,
        "quantity": 2
      }
    ]
  }'

Add Payment Info

POST /v1/checkout/add_payment_info

Track when a user adds payment information during checkout.

curl -X POST https://stat.axitrace.com/v1/checkout/add_payment_info \
  -u "sk_live_YOUR_SECRET_KEY:" \
  -H "Content-Type: application/json" \
  -H "User-Agent: MyApp/1.0" \
  -d '{
    "client_id": "user-123",
    "currency": "USD",
    "value": 199.98,
    "payment_type": "Credit Card",
    "items": [
      {
        "item_id": "PROD-001",
        "item_name": "Premium Widget",
        "price": 99.99,
        "quantity": 2
      }
    ]
  }'

Transaction

POST /v1/transaction

Track a completed purchase transaction.

This Is Not a GA4-Style Payload

Transactions do not use transaction_id, flat items[] with a scalar price, or a top-level value. The validated shape uses orderId, source, products[] with sku / finalUnitPrice, and Money objects ({amount, currency}) for every monetary field. A GA4-shaped payload is rejected with 400 before it reaches ClickHouse. See the full Transaction event reference for the complete field list.

curl -X POST https://stat.axitrace.com/v1/transaction \
  -u "sk_live_YOUR_SECRET_KEY:" \
  -H "Content-Type: application/json" \
  -H "User-Agent: MyApp/1.0" \
  -d '{
    "orderId": "ORD-2024-001234",
    "source": "WEB_DESKTOP",
    "client": {
        "customId": "user-123",
        "email": "customer@example.com"
    },
    "revenue": {
        "amount": 214.97,
        "currency": "USD"
    },
    "value": {
        "amount": 199.98,
        "currency": "USD"
    },
    "paymentInfo": {
        "method": "CARD"
    },
    "products": [
      {
        "sku": "PROD-001",
        "name": "Premium Widget",
        "finalUnitPrice": {
            "amount": 99.99,
            "currency": "USD"
        },
        "quantity": 2
      }
    ],
    "eventSalt": "ORD-2024-001234"
  }'
Field Required Notes
orderId Required Your order identifier
source Required One of WEB_DESKTOP, WEB_MOBILE, MOBILE_APP, POS, MOBILE, DESKTOP
client Required At least one of customId, id, uuid, email
revenue, value Required Money objects; must share the same currency as every product's finalUnitPrice
paymentInfo.method Required e.g. CASH, CARD, PAYPAL
products[] Required At least one item; each needs sku, name, finalUnitPrice (Money), quantity > 0
eventSalt Optional Use your order ID for idempotency on retries (client-side only - see Idempotency below)
tax, shipping, taxesIncluded Optional Order tax, shipping the buyer paid (tax included) and whether prices include tax (default true); used by profit tracking, kept with either key
costs.shipping, costs.paymentFee, costs.handling, products[].unitCost Optional Your costs (Money, revenue currency, >= 0, otherwise 400). Kept only with the Secret Key; removed from a Public Key request. See Profit and POAS
products[].externalId Optional Your product id, matched against the external_id of your profit cost catalog before the SKU

See the Transaction event reference for the full field list (products, discounts, Facebook CAPI matching fields, metadata) and complete server-side integration examples.

Refund

POST /v1/refund

Report a refund or a cancellation of an order you sent to /v1/transaction. Secret Key only: a Public Key request is answered 401. A refund reduces profit and POAS; revenue, ROAS and what ad platforms received stay unchanged.

curl -X POST https://stat.axitrace.com/v1/refund \
  -u "sk_live_YOUR_SECRET_KEY:" \
  -H "Content-Type: application/json" \
  -H "User-Agent: MyApp/1.0" \
  -d '{
    "orderId": "ORD-2024-001234",
    "refundId": "RF-2024-000077",
    "refundedAt": "2026-10-02T10:00:00Z",
    "amount": 99.99,
    "currency": "USD",
    "lines": [
      { "sku": "PROD-001", "quantity": 1, "amount": 99.99 }
    ]
  }'
Field Required Notes
orderId Required The orderId of the purchase
refundId Required Your refund id (at most 191 characters); a repeat within 30 days is ignored
amount, currency Optional Total refunded, gross, in the order currency; currency is required whenever an amount is sent
isCancellation Optional true reverses every product of the order
lines[] Optional Refunded products: sku or externalId, quantity, optional amount

At least one of amount, lines or isCancellation is required. See the Refund event reference for how a refund changes profit.

Search

POST /v1/search

Track search queries.

curl -X POST https://stat.axitrace.com/v1/search \
  -u "sk_live_YOUR_SECRET_KEY:" \
  -H "Content-Type: application/json" \
  -H "User-Agent: MyApp/1.0" \
  -d '{
    "client_id": "user-123",
    "search_term": "premium widget",
    "results_count": 42
  }'

Subscribe

POST /v1/subscribe

Track newsletter or mailing list subscriptions.

curl -X POST https://stat.axitrace.com/v1/subscribe \
  -u "sk_live_YOUR_SECRET_KEY:" \
  -H "Content-Type: application/json" \
  -H "User-Agent: MyApp/1.0" \
  -d '{
    "client_id": "user-123",
    "email": "customer@example.com",
    "subscription_type": "newsletter"
  }'

Optional: eventSalt (a retry with the same value is stored once), value with currency, and products in the transaction line shape. See Leads: HTTP API.

Start Trial

POST /v1/start_trial

Track when a user starts a free trial.

curl -X POST https://stat.axitrace.com/v1/start_trial \
  -u "sk_live_YOUR_SECRET_KEY:" \
  -H "Content-Type: application/json" \
  -H "User-Agent: MyApp/1.0" \
  -d '{
    "client_id": "user-123",
    "trial_value": 49.99,
    "trial_currency": "USD",
    "trial_period_days": 14,
    "plan_name": "Premium Plan"
  }'

Optional: eventSalt (a retry with the same value is stored once) and products in the transaction line shape, priced in trial_currency. See Leads: HTTP API.

Response Format

Success Response

All successful requests return HTTP 200 with:

{
  "success": true,
  "eventId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "action": "event_name"
}

Error Responses

Status Code Meaning Response Body
400 Bad Request - Invalid JSON or missing required fields {"error": "description of error"}
401 Unauthorized - Invalid or missing authentication {"error": "unauthorized"}
403 Forbidden - Workspace inactive or domain not verified {"error": "workspace inactive"}
429 Too Many Requests - Rate limit exceeded {"error": "rate limit exceeded"}
500 Internal Server Error {"error": "internal error"}

Required Headers

Header Required Description
Content-Type Yes Must be application/json
User-Agent Yes Identifies your application (e.g., MyApp/1.0)
Authorization Yes Basic auth with Secret Key
User-Agent Required

Requests without a proper User-Agent header (or with generic user agents like curl/8.x) may be filtered as bot traffic. Always include a descriptive User-Agent that identifies your application.

Code Examples

<?php
$secretKey = getenv('AXITRACE_SECRET_KEY');

function trackEvent($endpoint, $data) {
    global $secretKey;

    $ch = curl_init("https://stat.axitrace.com/v1/{$endpoint}");
    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_POST => true,
        CURLOPT_USERPWD => $secretKey . ':',
        CURLOPT_HTTPHEADER => [
            'Content-Type: application/json',
            'User-Agent: MyApp/1.0'
        ],
        CURLOPT_POSTFIELDS => json_encode($data)
    ]);

    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    return [
        'status' => $httpCode,
        'data' => json_decode($response, true)
    ];
}

// Track a transaction (real schema - see /docs/events/transaction for the full field list)
$result = trackEvent('transaction', [
    'orderId' => 'ORD-' . uniqid(),
    'source' => 'WEB_DESKTOP',
    'client' => ['customId' => 'user-123'],
    'revenue' => ['amount' => 99.99, 'currency' => 'USD'],
    'value' => ['amount' => 99.99, 'currency' => 'USD'],
    'paymentInfo' => ['method' => 'CARD'],
    'products' => [
        [
            'sku' => 'PROD-001',
            'name' => 'Widget',
            'finalUnitPrice' => ['amount' => 99.99, 'currency' => 'USD'],
            'quantity' => 1,
        ],
    ],
]);

if ($result['status'] === 200) {
    echo "Event tracked: " . $result['data']['transactionId'];
}
import os
import requests

secret_key = os.environ.get('AXITRACE_SECRET_KEY')
base_url = 'https://stat.axitrace.com/v1'

def track_event(endpoint, data):
    response = requests.post(
        f'{base_url}/{endpoint}',
        auth=(secret_key, ''),
        headers={
            'Content-Type': 'application/json',
            'User-Agent': 'MyApp/1.0'
        },
        json=data
    )
    return response.json()

# Track a transaction (real schema - see /docs/events/transaction for the full field list)
result = track_event('transaction', {
    'orderId': 'TXN-12345',
    'source': 'WEB_DESKTOP',
    'client': {'customId': 'user-123'},
    'revenue': {'amount': 99.99, 'currency': 'USD'},
    'value': {'amount': 99.99, 'currency': 'USD'},
    'paymentInfo': {'method': 'CARD'},
    'products': [
        {
            'sku': 'PROD-001',
            'name': 'Widget',
            'finalUnitPrice': {'amount': 99.99, 'currency': 'USD'},
            'quantity': 1,
        },
    ],
})

print(f"Event tracked: {result['transactionId']}")
const axios = require('axios');

const secretKey = process.env.AXITRACE_SECRET_KEY;
const baseUrl = 'https://stat.axitrace.com/v1';

async function trackEvent(endpoint, data) {
  const response = await axios.post(
    `${baseUrl}/${endpoint}`,
    data,
    {
      auth: { username: secretKey, password: '' },
      headers: {
        'Content-Type': 'application/json',
        'User-Agent': 'MyApp/1.0'
      }
    }
  );
  return response.data;
}

// Track a transaction (real schema - see /docs/events/transaction for the full field list)
const result = await trackEvent('transaction', {
  orderId: 'TXN-12345',
  source: 'WEB_DESKTOP',
  client: { customId: 'user-123' },
  revenue: { amount: 99.99, currency: 'USD' },
  value: { amount: 99.99, currency: 'USD' },
  paymentInfo: { method: 'CARD' },
  products: [
    {
      sku: 'PROD-001',
      name: 'Widget',
      finalUnitPrice: { amount: 99.99, currency: 'USD' },
      quantity: 1,
    },
  ],
});

console.log(`Event tracked: ${result.transactionId}`);
require 'net/http'
require 'json'
require 'uri'

SECRET_KEY = ENV['AXITRACE_SECRET_KEY']
BASE_URL = 'https://stat.axitrace.com/v1'

def track_event(endpoint, data)
  uri = URI("#{BASE_URL}/#{endpoint}")
  http = Net::HTTP.new(uri.host, uri.port)
  http.use_ssl = true

  request = Net::HTTP::Post.new(uri)
  request.basic_auth(SECRET_KEY, '')
  request['Content-Type'] = 'application/json'
  request['User-Agent'] = 'MyApp/1.0'
  request.body = data.to_json

  response = http.request(request)
  JSON.parse(response.body)
end

# Track a transaction (real schema - see /docs/events/transaction for the full field list)
result = track_event('transaction', {
  orderId: 'TXN-12345',
  source: 'WEB_DESKTOP',
  client: { customId: 'user-123' },
  revenue: { amount: 99.99, currency: 'USD' },
  value: { amount: 99.99, currency: 'USD' },
  paymentInfo: { method: 'CARD' },
  products: [
    {
      sku: 'PROD-001',
      name: 'Widget',
      finalUnitPrice: { amount: 99.99, currency: 'USD' },
      quantity: 1,
    },
  ],
})

puts "Event tracked: #{result['transactionId']}"

Rate Limiting

The API enforces rate limits to ensure fair usage. Current limits are:

  • Per-IP limit: 500 requests per minute
  • Per-workspace limit: 1,000 requests per minute by default (based on your plan)

When you exceed rate limits, the API returns HTTP 429. Implement exponential backoff in your code to handle this gracefully.

Idempotency

Only Some Endpoints Deduplicate Server-Side

Deduplication is keyed on the eventSalt you send. Send the same salt twice and the second request is answered 200 OK and ignored, so a retry is safe. Send no salt and every request is a new event.

  • /v1/transaction deduplicates for 30 days. The window is long on purpose: a duplicate purchase is rarely a double-clicked button, it is an order re-sent hours or days later by a webhook redelivery, a queue retry or an outbox being drained after an outage. Set eventSalt to something stable and unique per order - your order ID is the obvious choice.
  • /v1/custom-events deduplicates for 5 minutes, on event_id.
  • Every other /v1/* endpoint on this page does not deduplicate. A repeated page view, product view or checkout step is treated as a genuine second event, because for those it usually is one.

For the endpoints that do not deduplicate, you remain responsible for idempotency on your side - for example, only sending the event once you have durably recorded that you sent it. And because deduplication state is cached rather than stored forever, treat it as a safety net for retries, not as a replacement for a unique constraint in your own database. See Timing & Deduplication for the full picture, including how /track's eventSalt dedup works and the conversion-event processing delay.