Trackli
API Reference

API Reference

Trackli REST API reference. Record affiliate conversions and track orders programmatically using API key authentication.

Authentication

Trackli uses API keys to authenticate requests to the public ingestion endpoints. Generate a key from your dashboard under Settings. Include it in every request as an X-API-Key header. The API key is accepted on POST /api/conversion and POST /api/track/order.

X-API-Key header

curl -X POST https://trytrackli.com/api/conversion \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key_here" \
  -d '{"customerEmail": "...", "affiliateRefCode": "...", "orderAmount": 4900}'

A missing or invalid key returns 401 Unauthorized. Keep your key secure and never expose it in client-side code or URLs.

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. Authenticated via X-API-Key header.

Request body

{
  "customerEmail": "customer@example.com",  // required
  "affiliateRefCode": "partner123",         // required
  "orderAmount": 4900,                      // required, integer cents
  "currency": "usd",                        // optional, default "usd"
  "stripeEventId": "evt_1abc"               // optional, for deduplication
}

curl example

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

Track an order from your payment processor and automatically calculate the affiliate commission. The stripeEventId is used for deduplication. Authenticated via X-API-Key header.

Request body

{
  "stripeEventId": "evt_1abc",              // required, used for deduplication
  "amountTotal": 4900,                      // required, integer cents
  "customerEmail": "customer@example.com",  // required
  "affiliateRefCode": "partner123",         // required
  "currency": "usd"                         // optional, default "usd"
}

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 '{
    "stripeEventId": "evt_1abc",
    "amountTotal": 4900,
    "customerEmail": "customer@example.com",
    "affiliateRefCode": "partner123",
    "currency": "usd"
  }'
GET
/api/affiliates

List all affiliates in your program. This endpoint requires a dashboard session (log in at trytrackli.com/login) — it is not accessible via API key.

GET
/api/commissions

List all commissions across your program. This endpoint requires a dashboard session (log in at trytrackli.com/login) — it is not accessible via API key.

Idempotency

To avoid recording duplicate conversions, Trackli deduplicates requests. For POST /api/conversion, pass an optional stripeEventId for deduplication — if omitted, a unique ID is generated automatically. For POST /api/track/order, the required stripeEventId field is used for deduplication. If the same event ID is submitted again, the API returns a 409 instead of creating a duplicate.

When using Stripe webhooks, pass the Stripe event ID as stripeEventId. Trackli stores the event ID and ignores any duplicate webhook deliveries automatically, ensuring 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 '{"customerEmail": "buyer@example.com", "affiliateRefCode": "partner123", "orderAmount": 4900, "stripeEventId": "evt_1abc"}'
# => 201 Created

# Second identical request - duplicate rejected
curl -X POST https://trytrackli.com/api/conversion \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key_here" \
  -d '{"customerEmail": "buyer@example.com", "affiliateRefCode": "partner123", "orderAmount": 4900, "stripeEventId": "evt_1abc"}'
# => 409 Conflict (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 (copy the exact URL from Trackli Settings > Stripe)
POST https://trytrackli.com/api/webhook/stripe/<your-account-id>

# 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
500 Server Error    - Internal server error

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

Rate Limits

Rate limiting is planned for a future release to ensure fair usage and platform stability. At launch, there are no enforced per-key request caps. We will announce plan-based limits with advance notice before they take effect.

As a best practice, we recommend implementing exponential backoff in your integration so it is ready when limits are introduced.

Next Steps

Get started quickly or dive deeper into the documentation.