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 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:"
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/jsonheaderUser-Agentheader (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.
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.
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 |
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
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/transactiondeduplicates 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. SeteventSaltto something stable and unique per order - your order ID is the obvious choice. -
/v1/custom-eventsdeduplicates for 5 minutes, onevent_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.