Track sale events
Endpoint
POST /api/track/sale
Track a sale conversion event for a short link. This endpoint creates a sale event and upserts a customer record.
Endpoint text
POST /api/track/saleAuthentication
Requires authentication with an API key that has the conversionsWrite scope.
Request Body
Accepts a single object (not an array). All fields are required unless marked optional.
| Parameter | Type | Required | Description |
|---|---|---|---|
customerExternalId (body) | string | Yes | Customer external ID (1-100 characters). Used to upsert the customer. |
amount (body) | integer | Yes | Sale amount (non-negative integer). |
currency (body) | string | No | Currency code. Defaults to "usd". |
eventName (body) | string | No | Sale event name. Defaults to "Purchase" (max 255 characters). |
metadata (body) | object | No | Optional metadata object stored with the sale event. |
leadEventName (body) | string | No | Lead event name to attribute this sale to a specific lead. |
clickId (body) | string | No | Click ID for direct sale attribution. |
customerName (body) | string | Yes | Customer name (max 100 characters). |
customerEmail (body) | string (email) | No | Customer email. Optional. Can be null to clear. |
customerAvatar (body) | string (URL) | No | Customer avatar URL. Optional. Can be null to clear. |
Capture clickId in the browser
If you want to attribute a sale directly to a click, use the Browser attribution script to persist `hoko_id` and pass it as clickId. See [Browser attribution script](/docs/track/analytics-js).
Attribution Priority
The sale is attributed in this order: leadEventName (if provided) → clickId (if provided) → most recent lead for the customer. If no lead exists and no clickId is provided, the request fails.