Track sale events

Endpoint

POST /track/sale

Track a sale conversion event for a short link. This endpoint creates a sale event and upserts a customer record.

Every accepted POST creates a new sale, including a retry. This includes caller retries. Retrying the same request reuses the active customer but intentionally records another sale. No Idempotency-Key header is accepted, promised, or required. Retry only when another sale conversion is intended.

Endpoint text 
POST /track/sale

Authentication

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.

ParameterTypeRequiredDescription
customerExternalId (body)stringYesCustomer external ID (1-100 characters). Used to upsert the customer.
amount (body)integerYesSale amount (non-negative integer).
currency (body)stringNoCurrency code. Defaults to "usd".
eventName (body)stringNoSale event name. Defaults to "Purchase" (max 255 characters).
metadata (body)objectNoOptional metadata object stored with the sale event.
leadEventName (body)stringNoLead event name to attribute this sale to a specific lead.
clickId (body)stringNoClick ID string for direct sale attribution.
customerName (body)stringYesCustomer name (max 100 characters).
customerEmail (body)string (email)NoCustomer email, max 100 characters. Optional. Can be null to clear.
customerAvatar (body)string (URL)NoHTTPS 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](https://docs.hoko.to/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.