API Reference

Trackli REST API reference. Track conversions, manage affiliates, and query commission data programmatically.

Authentication

Trackli uses API keys to authenticate requests. Generate a key from your dashboard under Settings. Include it in every request using one of two methods:

Option 1: X-API-Key header (recommended)

curl -H "X-API-Key: your_api_key_here" \
  https://trytrackli.com/api/affiliates

Option 2: Query parameter

curl https://trytrackli.com/api/affiliates?api_key=your_api_key_here

The header method is recommended for security, as query parameters may be logged in server access logs and browser history.

Base URL

All API endpoints are relative to the following base URL:

https://trytrackli.com/api

Endpoints

POST

/api/conversion

Record a conversion when a referred customer completes a purchase or sign-up.

Request body

{
  "email": "customer@example.com",
  "refCode": "partner123",
  "amount": 4900,
  "currency": "usd"
}

curl example

curl -X POST https://trytrackli.com/api/conversion \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key_here" \
  -d '{
    "email": "customer@example.com",
    "refCode": "partner123",
    "amount": 4900,
    "currency": "usd"
  }'

POST

/api/track/order

Track an order and automatically calculate the affiliate commission.

Request body

{
  "email": "customer@example.com",
  "amount": 4900,
  "refCode": "partner123"
}

curl example

curl -X POST https://trytrackli.com/api/track/order \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key_here" \
  -d '{
    "email": "customer@example.com",
    "amount": 4900,
    "refCode": "partner123"
  }'

GET

/api/affiliates

List all affiliates in your program. Requires authentication.

curl example

curl https://trytrackli.com/api/affiliates \
  -H "X-API-Key: your_api_key_here"

# Response
{
  "affiliates": [
    {
      "id": 1,
      "name": "Jane Doe",
      "email": "jane@example.com",
      "refCode": "partner123",
      "clicks": 142,
      "conversions": 12
    }
  ]
}

GET

/api/commissions

List all commissions across your program. Requires authentication.

curl example

curl https://trytrackli.com/api/commissions \
  -H "X-API-Key: your_api_key_here"

# Response
{
  "commissions": [
    {
      "id": 1,
      "affiliateId": 1,
      "amount": 980,
      "currency": "usd",
      "status": "pending",
      "createdAt": "2026-02-20T10:30:00Z"
    }
  ]
}

Idempotency

To avoid recording duplicate conversions, Trackli deduplicates requests based on the combination of email and refCode. If a conversion with the same email and referral code already exists, the API will return the existing record instead of creating a duplicate.

For Stripe webhook events, Trackli stores the event ID and ignores any duplicate webhook deliveries automatically. This ensures that retried webhooks do not create duplicate commissions.

# First request - creates conversion
curl -X POST https://trytrackli.com/api/conversion \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key_here" \
  -d '{"email": "buyer@example.com", "refCode": "partner123", "amount": 4900, "currency": "usd"}'
# => 201 Created

# Second identical request - returns existing record
curl -X POST https://trytrackli.com/api/conversion \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key_here" \
  -d '{"email": "buyer@example.com", "refCode": "partner123", "amount": 4900, "currency": "usd"}'
# => 200 OK (no duplicate created)

Webhook Events

Trackli listens for Stripe webhook events to automatically record conversions and calculate commissions. Configure your Stripe webhook to point to your Trackli endpoint.

Supported events

checkout.session.completed— Triggered when a customer completes a Stripe Checkout session. Trackli matches the customer email to a referral and creates a commission.
invoice.payment_succeeded— Triggered on successful subscription renewal payments. Used for recurring commission tracking.

# Stripe webhook endpoint
POST https://trytrackli.com/api/stripe/webhook

# Headers (set by Stripe automatically):
# Stripe-Signature: t=...,v1=...

# Trackli verifies the signature using your webhook secret
# and processes the event automatically.

Error Handling

The API returns standard HTTP status codes. Errors include a JSON body with a message field describing the issue.

# Common HTTP status codes
200 OK              - Request succeeded
201 Created         - Resource created successfully
400 Bad Request     - Invalid request body or missing required fields
401 Unauthorized    - Missing or invalid API key
404 Not Found       - Resource not found
429 Too Many Reqs   - Rate limit exceeded
500 Server Error    - Internal server error

# Example error response
{
  "message": "Invalid or missing API key",
  "status": 401
}

Rate Limits

API requests are rate-limited to ensure fair usage and platform stability. Limits are applied per API key.

Plan	Rate Limit	Burst
Free	100 requests/minute	10 requests/second
Starter	500 requests/minute	50 requests/second
Pro	2,000 requests/minute	200 requests/second

When you exceed the rate limit, the API responds with a 429 Too Many Requests status. Implement exponential backoff in your client to handle rate limiting gracefully.

Next Steps

Get started quickly or dive deeper into the documentation.