Track a sale

curl --request POST \
  --url https://biq.li/api/v1/track/sale \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "customerExternalId": "<string>",
  "amount": 4503599627370495,
  "clickId": "<string>",
  "currency": "usd",
  "eventName": "Purchase",
  "paymentProcessor": "custom",
  "invoiceId": "<string>",
  "leadEventName": "<string>",
  "customerName": "<string>",
  "customerEmail": "jsmith@example.com",
  "customerAvatar": "<string>",
  "eventId": "<string>",
  "metadata": {},
  "occurredAt": "2023-11-07T05:31:56Z"
}
'

import requests

url = "https://biq.li/api/v1/track/sale"

payload = {
    "customerExternalId": "<string>",
    "amount": 4503599627370495,
    "clickId": "<string>",
    "currency": "usd",
    "eventName": "Purchase",
    "paymentProcessor": "custom",
    "invoiceId": "<string>",
    "leadEventName": "<string>",
    "customerName": "<string>",
    "customerEmail": "jsmith@example.com",
    "customerAvatar": "<string>",
    "eventId": "<string>",
    "metadata": {},
    "occurredAt": "2023-11-07T05:31:56Z"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    customerExternalId: '<string>',
    amount: 4503599627370495,
    clickId: '<string>',
    currency: 'usd',
    eventName: 'Purchase',
    paymentProcessor: 'custom',
    invoiceId: '<string>',
    leadEventName: '<string>',
    customerName: '<string>',
    customerEmail: 'jsmith@example.com',
    customerAvatar: '<string>',
    eventId: '<string>',
    metadata: {},
    occurredAt: '2023-11-07T05:31:56Z'
  })
};

fetch('https://biq.li/api/v1/track/sale', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://biq.li/api/v1/track/sale",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'customerExternalId' => '<string>',
    'amount' => 4503599627370495,
    'clickId' => '<string>',
    'currency' => 'usd',
    'eventName' => 'Purchase',
    'paymentProcessor' => 'custom',
    'invoiceId' => '<string>',
    'leadEventName' => '<string>',
    'customerName' => '<string>',
    'customerEmail' => 'jsmith@example.com',
    'customerAvatar' => '<string>',
    'eventId' => '<string>',
    'metadata' => [
        
    ],
    'occurredAt' => '2023-11-07T05:31:56Z'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://biq.li/api/v1/track/sale"

	payload := strings.NewReader("{\n  \"customerExternalId\": \"<string>\",\n  \"amount\": 4503599627370495,\n  \"clickId\": \"<string>\",\n  \"currency\": \"usd\",\n  \"eventName\": \"Purchase\",\n  \"paymentProcessor\": \"custom\",\n  \"invoiceId\": \"<string>\",\n  \"leadEventName\": \"<string>\",\n  \"customerName\": \"<string>\",\n  \"customerEmail\": \"jsmith@example.com\",\n  \"customerAvatar\": \"<string>\",\n  \"eventId\": \"<string>\",\n  \"metadata\": {},\n  \"occurredAt\": \"2023-11-07T05:31:56Z\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://biq.li/api/v1/track/sale")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"customerExternalId\": \"<string>\",\n  \"amount\": 4503599627370495,\n  \"clickId\": \"<string>\",\n  \"currency\": \"usd\",\n  \"eventName\": \"Purchase\",\n  \"paymentProcessor\": \"custom\",\n  \"invoiceId\": \"<string>\",\n  \"leadEventName\": \"<string>\",\n  \"customerName\": \"<string>\",\n  \"customerEmail\": \"jsmith@example.com\",\n  \"customerAvatar\": \"<string>\",\n  \"eventId\": \"<string>\",\n  \"metadata\": {},\n  \"occurredAt\": \"2023-11-07T05:31:56Z\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://biq.li/api/v1/track/sale")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"customerExternalId\": \"<string>\",\n  \"amount\": 4503599627370495,\n  \"clickId\": \"<string>\",\n  \"currency\": \"usd\",\n  \"eventName\": \"Purchase\",\n  \"paymentProcessor\": \"custom\",\n  \"invoiceId\": \"<string>\",\n  \"leadEventName\": \"<string>\",\n  \"customerName\": \"<string>\",\n  \"customerEmail\": \"jsmith@example.com\",\n  \"customerAvatar\": \"<string>\",\n  \"eventId\": \"<string>\",\n  \"metadata\": {},\n  \"occurredAt\": \"2023-11-07T05:31:56Z\"\n}"

response = http.request(request)
puts response.read_body

{
  "event": {
    "id": "<string>",
    "eventName": "<string>",
    "type": "lead",
    "occurredAt": "2023-11-07T05:31:56Z"
  },
  "click": {
    "id": "<string>"
  },
  "link": {
    "id": "<string>",
    "shortUrl": "<string>",
    "destinationUrl": "<string>"
  },
  "customer": {
    "id": "<string>",
    "externalId": "<string>",
    "name": "<string>",
    "email": "jsmith@example.com",
    "avatar": "<string>"
  },
  "request_id": "<string>",
  "sale": {
    "amount": 1,
    "currency": "<string>",
    "amountUsd": 1,
    "paymentProcessor": "<string>",
    "invoiceId": "<string>"
  }
}

{
  "error": {
    "code": "invalid_token",
    "message": "<string>",
    "details": {}
  },
  "request_id": "<string>"
}

{
  "error": {
    "code": "invalid_token",
    "message": "<string>",
    "details": {}
  },
  "request_id": "<string>"
}

{
  "error": {
    "code": "invalid_token",
    "message": "<string>",
    "details": {}
  },
  "request_id": "<string>"
}

{
  "error": {
    "code": "invalid_token",
    "message": "<string>",
    "details": {}
  },
  "request_id": "<string>"
}

{
  "error": {
    "code": "invalid_token",
    "message": "<string>",
    "details": {}
  },
  "request_id": "<string>"
}

{
  "error": {
    "code": "invalid_token",
    "message": "<string>",
    "details": {}
  },
  "request_id": "<string>"
}

{
  "error": {
    "code": "invalid_token",
    "message": "<string>",
    "details": {}
  },
  "request_id": "<string>"
}

{
  "error": {
    "code": "invalid_token",
    "message": "<string>",
    "details": {}
  },
  "request_id": "<string>"
}

POST

track

sale

Track a sale

curl --request POST \
  --url https://biq.li/api/v1/track/sale \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "customerExternalId": "<string>",
  "amount": 4503599627370495,
  "clickId": "<string>",
  "currency": "usd",
  "eventName": "Purchase",
  "paymentProcessor": "custom",
  "invoiceId": "<string>",
  "leadEventName": "<string>",
  "customerName": "<string>",
  "customerEmail": "jsmith@example.com",
  "customerAvatar": "<string>",
  "eventId": "<string>",
  "metadata": {},
  "occurredAt": "2023-11-07T05:31:56Z"
}
'

import requests

url = "https://biq.li/api/v1/track/sale"

payload = {
    "customerExternalId": "<string>",
    "amount": 4503599627370495,
    "clickId": "<string>",
    "currency": "usd",
    "eventName": "Purchase",
    "paymentProcessor": "custom",
    "invoiceId": "<string>",
    "leadEventName": "<string>",
    "customerName": "<string>",
    "customerEmail": "jsmith@example.com",
    "customerAvatar": "<string>",
    "eventId": "<string>",
    "metadata": {},
    "occurredAt": "2023-11-07T05:31:56Z"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    customerExternalId: '<string>',
    amount: 4503599627370495,
    clickId: '<string>',
    currency: 'usd',
    eventName: 'Purchase',
    paymentProcessor: 'custom',
    invoiceId: '<string>',
    leadEventName: '<string>',
    customerName: '<string>',
    customerEmail: 'jsmith@example.com',
    customerAvatar: '<string>',
    eventId: '<string>',
    metadata: {},
    occurredAt: '2023-11-07T05:31:56Z'
  })
};

fetch('https://biq.li/api/v1/track/sale', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://biq.li/api/v1/track/sale",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'customerExternalId' => '<string>',
    'amount' => 4503599627370495,
    'clickId' => '<string>',
    'currency' => 'usd',
    'eventName' => 'Purchase',
    'paymentProcessor' => 'custom',
    'invoiceId' => '<string>',
    'leadEventName' => '<string>',
    'customerName' => '<string>',
    'customerEmail' => 'jsmith@example.com',
    'customerAvatar' => '<string>',
    'eventId' => '<string>',
    'metadata' => [
        
    ],
    'occurredAt' => '2023-11-07T05:31:56Z'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://biq.li/api/v1/track/sale"

	payload := strings.NewReader("{\n  \"customerExternalId\": \"<string>\",\n  \"amount\": 4503599627370495,\n  \"clickId\": \"<string>\",\n  \"currency\": \"usd\",\n  \"eventName\": \"Purchase\",\n  \"paymentProcessor\": \"custom\",\n  \"invoiceId\": \"<string>\",\n  \"leadEventName\": \"<string>\",\n  \"customerName\": \"<string>\",\n  \"customerEmail\": \"jsmith@example.com\",\n  \"customerAvatar\": \"<string>\",\n  \"eventId\": \"<string>\",\n  \"metadata\": {},\n  \"occurredAt\": \"2023-11-07T05:31:56Z\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://biq.li/api/v1/track/sale")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"customerExternalId\": \"<string>\",\n  \"amount\": 4503599627370495,\n  \"clickId\": \"<string>\",\n  \"currency\": \"usd\",\n  \"eventName\": \"Purchase\",\n  \"paymentProcessor\": \"custom\",\n  \"invoiceId\": \"<string>\",\n  \"leadEventName\": \"<string>\",\n  \"customerName\": \"<string>\",\n  \"customerEmail\": \"jsmith@example.com\",\n  \"customerAvatar\": \"<string>\",\n  \"eventId\": \"<string>\",\n  \"metadata\": {},\n  \"occurredAt\": \"2023-11-07T05:31:56Z\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://biq.li/api/v1/track/sale")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"customerExternalId\": \"<string>\",\n  \"amount\": 4503599627370495,\n  \"clickId\": \"<string>\",\n  \"currency\": \"usd\",\n  \"eventName\": \"Purchase\",\n  \"paymentProcessor\": \"custom\",\n  \"invoiceId\": \"<string>\",\n  \"leadEventName\": \"<string>\",\n  \"customerName\": \"<string>\",\n  \"customerEmail\": \"jsmith@example.com\",\n  \"customerAvatar\": \"<string>\",\n  \"eventId\": \"<string>\",\n  \"metadata\": {},\n  \"occurredAt\": \"2023-11-07T05:31:56Z\"\n}"

response = http.request(request)
puts response.read_body

{
  "event": {
    "id": "<string>",
    "eventName": "<string>",
    "type": "lead",
    "occurredAt": "2023-11-07T05:31:56Z"
  },
  "click": {
    "id": "<string>"
  },
  "link": {
    "id": "<string>",
    "shortUrl": "<string>",
    "destinationUrl": "<string>"
  },
  "customer": {
    "id": "<string>",
    "externalId": "<string>",
    "name": "<string>",
    "email": "jsmith@example.com",
    "avatar": "<string>"
  },
  "request_id": "<string>",
  "sale": {
    "amount": 1,
    "currency": "<string>",
    "amountUsd": 1,
    "paymentProcessor": "<string>",
    "invoiceId": "<string>"
  }
}

{
  "error": {
    "code": "invalid_token",
    "message": "<string>",
    "details": {}
  },
  "request_id": "<string>"
}

{
  "error": {
    "code": "invalid_token",
    "message": "<string>",
    "details": {}
  },
  "request_id": "<string>"
}

{
  "error": {
    "code": "invalid_token",
    "message": "<string>",
    "details": {}
  },
  "request_id": "<string>"
}

{
  "error": {
    "code": "invalid_token",
    "message": "<string>",
    "details": {}
  },
  "request_id": "<string>"
}

{
  "error": {
    "code": "invalid_token",
    "message": "<string>",
    "details": {}
  },
  "request_id": "<string>"
}

{
  "error": {
    "code": "invalid_token",
    "message": "<string>",
    "details": {}
  },
  "request_id": "<string>"
}

{
  "error": {
    "code": "invalid_token",
    "message": "<string>",
    "details": {}
  },
  "request_id": "<string>"
}

{
  "error": {
    "code": "invalid_token",
    "message": "<string>",
    "details": {}
  },
  "request_id": "<string>"
}

Use this endpoint from a trusted server after a paid order, subscription, renewal, or other revenue event.

Authentication and permission

Send a secret biqli_... workspace API key with Conversions: Write (conversions.create). The key selects the workspace. Never expose it in browser code and never send a workspace ID.

Direct sale request

Pass clickId when the checkout or order still carries the Biqli bq_id. Amounts are integers in the currency’s minor unit, so $54.99 is 5499 for usd.

curl --request POST \
  --url https://biq.li/api/v1/track/sale \
  --header "Authorization: Bearer $BIQLI_API_KEY" \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: order_2026_1842' \
  --header 'X-Biq-Client: acme-backend' \
  --header 'X-Biq-Client-Version: 1.4.0' \
  --data '{
    "clickId": "fGQimsCLcpoa",
    "customerExternalId": "customer_1842",
    "amount": 5499,
    "currency": "usd",
    "eventName": "Purchase",
    "paymentProcessor": "stripe",
    "invoiceId": "in_1842",
    "eventId": "sale_order_2026_1842",
    "metadata": {
      "orderId": "order_2026_1842"
    }
  }'

Deferred sale request

After a lead has established customer attribution, you may omit clickId. Biqli first uses the named lead when leadEventName is present, then the customer attribution selected by the workspace’s first-click or last-click model.

{
  "customerExternalId": "customer_1842",
  "amount": 1299,
  "currency": "usd",
  "eventName": "Renewal",
  "paymentProcessor": "stripe",
  "invoiceId": "in_renewal_1842_02",
  "leadEventName": "Signed up"
}

Field	Required	Description
`customerExternalId`	Yes	Stable customer ID from your system, from 1 to 100 characters.
`amount`	Yes	Non-negative integer in the currency’s minor unit.
`currency`	No	Supported lowercase ISO 4217 code. Defaults to `usd`.
`clickId`	Conditional	Direct attribution click. Omit only when the customer already has eligible attribution.
`eventName`	No	Sale name. Defaults to `Purchase`.
`paymentProcessor`	No	Lowercase processor namespace. Defaults to `custom`.
`invoiceId`	Recommended	Durable invoice identifier, unique per workspace and payment processor.
`leadEventName`	No	Prefer attribution from this customer’s matching lead event.
`customerName`, `customerEmail`, `customerAvatar`	No	Optional customer identity fields.
`eventId`	No	Stable event identifier, from 1 to 100 safe identifier characters.
`metadata`	No	Bounded JSON metadata object. Keys contain 1 to 64 characters and cannot be numeric-only.
`occurredAt`	No	ISO 8601 event time within the accepted clock window.

Idempotency

Use a stable invoiceId and paymentProcessor for durable financial-event deduplication. Also send Idempotency-Key for safe transport retries. An exact replay returns the original 201 response and the Idempotency-Replayed: true header without repeating side effects. Reusing an invoice, event, or idempotency identifier with different data returns 409 idempotency_conflict.

Response

The response includes the same event, click, link, customer, and request fields as a lead, plus normalized sale data:

{
  "event": {
    "id": "biq_sev_01M2C4AB8VQ3V45N1HTG8D7R2K",
    "eventName": "Purchase",
    "type": "sale",
    "occurredAt": "2026-09-13T10:30:00+00:00"
  },
  "click": {"id": "fGQimsCLcpoa"},
  "link": {
    "id": "biq_lnk_01M2BVVED2HDH0JVM5HV9WQ2F6",
    "shortUrl": "https://biq.li/3bKxigL",
    "destinationUrl": "https://example.com/checkout"
  },
  "customer": {
    "id": "biq_cus_01M2BW50TQD96C0QPCM6Z6WZNF",
    "externalId": "customer_1842",
    "name": "Ada Lovelace",
    "email": "ada@example.com",
    "avatar": null
  },
  "sale": {
    "amount": 5499,
    "currency": "usd",
    "amountUsd": 5499,
    "paymentProcessor": "stripe",
    "invoiceId": "in_1842"
  },
  "request_id": "c2fe3069-9416-47ed-928d-a96bf37cc690"
}

amountUsd is an integer in USD cents. A non-USD request requires a current exchange rate; otherwise the API returns 422 currency_unavailable.

Errors

Status	Code	Meaning
`401`	`invalid_token`	The workspace API key is missing, invalid, revoked, or the wrong credential type.
`403`	`insufficient_scope`	The key lacks `conversions.create`.
`403`	`tracking_disabled`	Conversion tracking is unavailable or disabled for the workspace.
`404`	`resource_not_found`	A supplied click is unavailable in this workspace.
`405`	`method_not_allowed`	This endpoint only accepts `POST`.
`409`	`idempotency_conflict`	An invoice, event, or idempotency identifier was reused with different data.
`422`	`attribution_required`	No direct or existing customer attribution was available.
`422`	`currency_unavailable`	No current exchange rate is available for the requested currency.
`422`	`validation_error`	The JSON body, amount, currency, metadata, or event time is invalid.
`429`	`rate_limit_exceeded`	The workspace exceeded its API request allowance.

Read Track a lead for customer attribution setup and Authentication for API-key rotation and least-privilege access.

Authorizations

Authorization

string

header

required

A workspace API key beginning with biqli_.

Headers

Idempotency-Key

string

Stable retry key. Reuse only for the same logical request and payload.

Required string length: 1 - 255

X-Biq-Client

string

Integration name recorded in API diagnostics.

Maximum string length: 64

X-Biq-Client-Version

string

Integration version recorded in API diagnostics.

Maximum string length: 64

X-Biq-Request-Id

string

Caller-generated request identifier for tracing.

Required string length: 1 - 100

Pattern: ^[A-Za-z0-9._:-]+$

Body

application/json

customerExternalId

string

required

Required string length: 1 - 100

amount

integer

required

Amount in the currency's minor unit.

Required range: 0 <= x <= 9007199254740991

clickId

string | null

Required string length: 1 - 100

Pattern: ^[A-Za-z0-9_-]+$

currency

string | null

default:usd

Pattern: ^[a-z]{3}$

eventName

string | null

default:Purchase

Required string length: 1 - 255

paymentProcessor

string | null

default:custom

Maximum string length: 32

Pattern: ^[a-z0-9](?:[a-z0-9._-]*[a-z0-9])?$

invoiceId

string | null

Required string length: 1 - 255

leadEventName

string | null

Required string length: 1 - 255

customerName

string | null

Maximum string length: 255

customerEmail

string<email> | null

Maximum string length: 254

customerAvatar

string<uri> | null

Maximum string length: 2048

Pattern: ^https?://

eventId

string | null

Required string length: 1 - 100

Pattern: ^[A-Za-z0-9](?:[A-Za-z0-9._:-]*[A-Za-z0-9])?$

metadata

object | null

occurredAt

string<date-time> | null

Pattern: Z$

Response

Sale created or idempotently replayed.

event

object

required

Show child attributes

click

object

required

Show child attributes

link

object | null

required

Show child attributes

customer

object

required

Show child attributes

request_id

string

required

sale

object

required

Show child attributes

GETTING STARTED

SDKs

BIQLI LINKS API

Track a sale

Authentication and permission

Direct sale request

Deferred sale request

Idempotency

Response

Errors

Authorizations

Headers

Body

Response

​Authentication and permission

​Direct sale request

​Deferred sale request

​Idempotency

​Response

​Errors

Authorizations

Headers

Body

Response

Authentication and permission

Direct sale request

Deferred sale request

Idempotency

Response

Errors