Conversions API

Your cart knows a sale happened. TrackPlay knows who watched. This endpoint joins them. Use it when your cart is not one of the supported integrations, or when you want to record a sale your cart never sees: a phone close, a manual invoice, an upsell in your own checkout.

If you sell through ClickBank, BuyGoods, Digistore24, ThriveCart, SamCart, WarriorPlus or JVZoo, you do not need this API. Connect the integration and the postback is wired for you.

Send a sale

Needs a token with the conversions:write scope. See Authentication.

curl https://app.trackplay.io/api/v1/conversions \
  -H "Authorization: Bearer tplt_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order_10482" \
  -d '{
    "video_code": "9f2c1a7e-4d3b-4a11-9e77-0b2c5d8e1f34",
    "session_code": "3b1e5c90-77aa-4f2d-8c31-6de0a9b41c22",
    "conversion_id": "order_10482",
    "conversion_value": 297.00,
    "conversion_currency": "USD",
    "conversion_product_name": "Pro Annual",
    "conversion_customer_email": "buyer@example.com"
  }'

await fetch('https://app.trackplay.io/api/v1/conversions', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer tplt_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
    'Content-Type': 'application/json',
    'Idempotency-Key': 'order_10482',
  },
  body: JSON.stringify({
    video_code: '9f2c1a7e-4d3b-4a11-9e77-0b2c5d8e1f34',
    session_code: '3b1e5c90-77aa-4f2d-8c31-6de0a9b41c22',
    conversion_id: 'order_10482',
    conversion_value: 297.00,
    conversion_currency: 'USD',
  }),
});

$ch = curl_init('https://app.trackplay.io/api/v1/conversions');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer tplt_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
        'Content-Type: application/json',
        'Idempotency-Key: order_10482',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'video_code' => '9f2c1a7e-4d3b-4a11-9e77-0b2c5d8e1f34',
        'session_code' => '3b1e5c90-77aa-4f2d-8c31-6de0a9b41c22',
        'conversion_id' => 'order_10482',
        'conversion_value' => 297.00,
    ]),
]);
$response = curl_exec($ch);

201 Created

{
  "recorded": true,
  "conversion_id": "order_10482",
  "video_code": "9f2c1a7e-4d3b-4a11-9e77-0b2c5d8e1f34",
  "attributed_to_split_test": true
}

Send the session

video_code is the only required field. But a sale with no session_code is a sale you cannot trace back to a viewer. It lands in your totals and nowhere else. Your play-to-sale rate, your retention-by-buyer curve, and your split-test winner all stay blind to it. Read the session from the player and carry it through your checkout:

const sessionCode = window.trackplay.getSessionId();
// put it in a hidden field, your cart's custom/passthrough param, whatever survives to
// your backend — then send it back here.

Most carts have a passthrough field for exactly this. It is the same mechanism the built-in cart integrations use.

Do not double count

Send an Idempotency-Key header on every call. The first response for a given key is cached for 24 hours. A retry carrying the same key replays that response (same status, same body, plus Idempotency-Replayed: true) and does not record a second sale.

Payment webhooks retry. Without an Idempotency-Key, a retried delivery books the sale twice and inflates your revenue. Use your order ID.

Fields

string

required

The video the sale is credited to. A conversion with no video cannot be attributed to anything.

string

The viewer’s session. Strongly recommended. See above.

string

Your order ID. Defaults to a generated UUID.

number

The sale amount. Feeds revenue, EPC, RPV, AOV and ROAS.

string

Three-letter code, e.g. USD.

string

object

Anything else you want kept with the sale.

boolean

Marks the row as a test so you can exclude it from reporting.

string

Send with split_test_variation_id, or send neither. One without the other cannot identify an arm, and a half-attributed sale looks valid while being wrong.

string

Send with split_test_id, or send neither.

string

When the sale happened, as a date-time. Defaults to now.

What happens next

A recorded conversion fans out to everything you have connected: webhooks, Zapier, Meta CAPI, TikTok Events, GA4, RedTrack, Everflow, and your CRM. It works exactly as a cart postback would. You do not wire those up twice.

Errors

401

The token could not be resolved to a workspace.

403: INSUFFICIENT_SCOPE

Your token lacks conversions:write.

404

No video with that video_code exists in this workspace. The response echoes the video_code you sent. A token can only ever write into its own workspace, so this usually means the code is from a different one.

422

Validation failed. Check conversion_currency is exactly 3 characters and that split_test_id/split_test_variation_id were sent together.

429

Rate limited. Writes are capped at 60 per minute per token.

503

The conversion could not be written. Retry with the same Idempotency-Key.

Getting Started

Guides

Endpoints

Send a sale

Send the session

Do not double count

Fields

What happens next

Errors

​Send a sale

​Send the session

​Do not double count

​Fields

​What happens next

​Errors

Send a sale

Send the session

Do not double count

Fields

What happens next

Errors