Track a sale conversion event with the CodeQR API

POST

track

sale

JavaScript

import CodeQR from '@codeqr/ts';

const client = new CodeQR({
  apiKey: process.env['CODEQR_API_KEY'], // This is the default and can be omitted
});

const response = await client.track.trackSale({ amount: 0, customerExternalId: 'x' });

console.log(response.amount);

curl --request POST \
  --url https://api.codeqr.io/track/sale \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "customerExternalId": "<string>",
  "amount": 1,
  "currency": "usd",
  "eventName": "Invoice paid",
  "paymentProcessor": "custom",
  "invoiceId": null,
  "metadata": null,
  "leadEventName": "Cloned template 1481267",
  "clickId": "<string>",
  "customerName": null,
  "customerEmail": null,
  "customerAvatar": null
}
'

import requests

url = "https://api.codeqr.io/track/sale"

payload = {
    "customerExternalId": "<string>",
    "amount": 1,
    "currency": "usd",
    "eventName": "Invoice paid",
    "paymentProcessor": "custom",
    "invoiceId": None,
    "metadata": None,
    "leadEventName": "Cloned template 1481267",
    "clickId": "<string>",
    "customerName": None,
    "customerEmail": None,
    "customerAvatar": None
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.codeqr.io/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' => 1,
    'currency' => 'usd',
    'eventName' => 'Invoice paid',
    'paymentProcessor' => 'custom',
    'invoiceId' => null,
    'metadata' => null,
    'leadEventName' => 'Cloned template 1481267',
    'clickId' => '<string>',
    'customerName' => null,
    'customerEmail' => null,
    'customerAvatar' => null
  ]),
  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://api.codeqr.io/track/sale"

	payload := strings.NewReader("{\n  \"customerExternalId\": \"<string>\",\n  \"amount\": 1,\n  \"currency\": \"usd\",\n  \"eventName\": \"Invoice paid\",\n  \"paymentProcessor\": \"custom\",\n  \"invoiceId\": null,\n  \"metadata\": null,\n  \"leadEventName\": \"Cloned template 1481267\",\n  \"clickId\": \"<string>\",\n  \"customerName\": null,\n  \"customerEmail\": null,\n  \"customerAvatar\": null\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://api.codeqr.io/track/sale")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"customerExternalId\": \"<string>\",\n  \"amount\": 1,\n  \"currency\": \"usd\",\n  \"eventName\": \"Invoice paid\",\n  \"paymentProcessor\": \"custom\",\n  \"invoiceId\": null,\n  \"metadata\": null,\n  \"leadEventName\": \"Cloned template 1481267\",\n  \"clickId\": \"<string>\",\n  \"customerName\": null,\n  \"customerEmail\": null,\n  \"customerAvatar\": null\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.codeqr.io/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\": 1,\n  \"currency\": \"usd\",\n  \"eventName\": \"Invoice paid\",\n  \"paymentProcessor\": \"custom\",\n  \"invoiceId\": null,\n  \"metadata\": null,\n  \"leadEventName\": \"Cloned template 1481267\",\n  \"clickId\": \"<string>\",\n  \"customerName\": null,\n  \"customerEmail\": null,\n  \"customerAvatar\": null\n}"

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

{
  "eventName": "<string>",
  "customerId": "<string>",
  "amount": 123,
  "paymentProcessor": "<string>",
  "invoiceId": "<string>",
  "currency": "<string>",
  "metadata": {}
}

{
  "error": {
    "code": "bad_request",
    "message": "The requested resource was not found.",
    "doc_url": "https://docs.codeqr.io/api-reference/errors#bad-request"
  }
}

{
  "error": {
    "code": "unauthorized",
    "message": "The requested resource was not found.",
    "doc_url": "https://docs.codeqr.io/api-reference/errors#unauthorized"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "The requested resource was not found.",
    "doc_url": "https://docs.codeqr.io/api-reference/errors#forbidden"
  }
}

{
  "error": {
    "code": "not_found",
    "message": "The requested resource was not found.",
    "doc_url": "https://docs.codeqr.io/api-reference/errors#not-found"
  }
}

{
  "error": {
    "code": "conflict",
    "message": "The requested resource was not found.",
    "doc_url": "https://docs.codeqr.io/api-reference/errors#conflict"
  }
}

{
  "error": {
    "code": "invite_expired",
    "message": "The requested resource was not found.",
    "doc_url": "https://docs.codeqr.io/api-reference/errors#invite-expired"
  }
}

{
  "error": {
    "code": "unprocessable_entity",
    "message": "The requested resource was not found.",
    "doc_url": "https://docs.codeqr.io/api-reference/errors#unprocessable-entity"
  }
}

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "The requested resource was not found.",
    "doc_url": "https://docs.codeqr.io/api-reference/errors#rate-limit_exceeded"
  }
}

{
  "error": {
    "code": "internal_server_error",
    "message": "The requested resource was not found.",
    "doc_url": "https://docs.codeqr.io/api-reference/errors#internal-server_error"
  }
}

Conversions endpoints require a Business plan subscription or higher.

Authorizations

Authorization

string

header

required

Default authentication mechanism

Body

application/json

customerExternalId

string

required

The unique ID of the customer in your system. Will be used to identify and attribute all future events to this customer.

Required string length: 1 - 100

amount

integer

required

The amount of the sale in the smallest unit of currency — cents for two-decimal currencies, the full integer for zero-decimal ones (e.g. 1437 JPY), thousandths for three-decimal ones (e.g. 1437 KWD fils).

Required range: x >= 0

currency

string

default:usd

The currency of the sale, as an ISO 4217 code. Reporting is always in USD: non-USD sales are converted at the exchange rate of the day the sale is recorded, and the original amount and currency are kept on the event. The rate is not re-applied later, so reported totals do not move with the exchange rate.

eventName

string

default:Purchase

The name of the sale event. Recommended format: Invoice paid or Subscription created.

Maximum string length: 255

Example:

"Invoice paid"

paymentProcessor

enum<string>

default:custom

The payment processor via which the sale was made.

Available options:

stripe,

shopify,

polar,

paddle,

revenuecat,

custom,

manual

invoiceId

string | null

The invoice ID of the sale. Can be used as a idempotency key – only one sale event can be recorded for a given invoice ID.

metadata

object | null

Additional metadata to be stored with the sale event. Max 10,000 characters when stringified.

Show child attributes

leadEventName

string | null

The name of the lead event that occurred before the sale (case-sensitive). This is used to associate the sale event with a particular lead event (instead of the latest lead event for a link-customer combination, which is the default behavior). For direct sale tracking, this field can also be used to specify the lead event name.

Example:

"Cloned template 1481267"

clickId

string | null

[For direct sale tracking]: The unique ID of the click that the sale conversion event is attributed to. You can read this value from cq_id cookie.

customerName

string | null

[For direct sale tracking]: The name of the customer. If not passed, a random name will be generated (e.g. “Big Red Caribou”).

Maximum string length: 100

customerEmail

string<email> | null

[For direct sale tracking]: The email address of the customer.

Maximum string length: 100

customerAvatar

string | null

[For direct sale tracking]: The avatar URL of the customer.

Response

A sale was tracked.

eventName

string

required

customerId

string

required

amount

number

required

paymentProcessor

string

required

invoiceId

string | null

required

currency

string

required

metadata

object | null

required

Show child attributes

JavaScript

import CodeQR from '@codeqr/ts';

const client = new CodeQR({
  apiKey: process.env['CODEQR_API_KEY'], // This is the default and can be omitted
});

const response = await client.track.trackSale({ amount: 0, customerExternalId: 'x' });

console.log(response.amount);

curl --request POST \
  --url https://api.codeqr.io/track/sale \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "customerExternalId": "<string>",
  "amount": 1,
  "currency": "usd",
  "eventName": "Invoice paid",
  "paymentProcessor": "custom",
  "invoiceId": null,
  "metadata": null,
  "leadEventName": "Cloned template 1481267",
  "clickId": "<string>",
  "customerName": null,
  "customerEmail": null,
  "customerAvatar": null
}
'

import requests

url = "https://api.codeqr.io/track/sale"

payload = {
    "customerExternalId": "<string>",
    "amount": 1,
    "currency": "usd",
    "eventName": "Invoice paid",
    "paymentProcessor": "custom",
    "invoiceId": None,
    "metadata": None,
    "leadEventName": "Cloned template 1481267",
    "clickId": "<string>",
    "customerName": None,
    "customerEmail": None,
    "customerAvatar": None
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.codeqr.io/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' => 1,
    'currency' => 'usd',
    'eventName' => 'Invoice paid',
    'paymentProcessor' => 'custom',
    'invoiceId' => null,
    'metadata' => null,
    'leadEventName' => 'Cloned template 1481267',
    'clickId' => '<string>',
    'customerName' => null,
    'customerEmail' => null,
    'customerAvatar' => null
  ]),
  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://api.codeqr.io/track/sale"

	payload := strings.NewReader("{\n  \"customerExternalId\": \"<string>\",\n  \"amount\": 1,\n  \"currency\": \"usd\",\n  \"eventName\": \"Invoice paid\",\n  \"paymentProcessor\": \"custom\",\n  \"invoiceId\": null,\n  \"metadata\": null,\n  \"leadEventName\": \"Cloned template 1481267\",\n  \"clickId\": \"<string>\",\n  \"customerName\": null,\n  \"customerEmail\": null,\n  \"customerAvatar\": null\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://api.codeqr.io/track/sale")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"customerExternalId\": \"<string>\",\n  \"amount\": 1,\n  \"currency\": \"usd\",\n  \"eventName\": \"Invoice paid\",\n  \"paymentProcessor\": \"custom\",\n  \"invoiceId\": null,\n  \"metadata\": null,\n  \"leadEventName\": \"Cloned template 1481267\",\n  \"clickId\": \"<string>\",\n  \"customerName\": null,\n  \"customerEmail\": null,\n  \"customerAvatar\": null\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.codeqr.io/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\": 1,\n  \"currency\": \"usd\",\n  \"eventName\": \"Invoice paid\",\n  \"paymentProcessor\": \"custom\",\n  \"invoiceId\": null,\n  \"metadata\": null,\n  \"leadEventName\": \"Cloned template 1481267\",\n  \"clickId\": \"<string>\",\n  \"customerName\": null,\n  \"customerEmail\": null,\n  \"customerAvatar\": null\n}"

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

{
  "eventName": "<string>",
  "customerId": "<string>",
  "amount": 123,
  "paymentProcessor": "<string>",
  "invoiceId": "<string>",
  "currency": "<string>",
  "metadata": {}
}

{
  "error": {
    "code": "bad_request",
    "message": "The requested resource was not found.",
    "doc_url": "https://docs.codeqr.io/api-reference/errors#bad-request"
  }
}

{
  "error": {
    "code": "unauthorized",
    "message": "The requested resource was not found.",
    "doc_url": "https://docs.codeqr.io/api-reference/errors#unauthorized"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "The requested resource was not found.",
    "doc_url": "https://docs.codeqr.io/api-reference/errors#forbidden"
  }
}

{
  "error": {
    "code": "not_found",
    "message": "The requested resource was not found.",
    "doc_url": "https://docs.codeqr.io/api-reference/errors#not-found"
  }
}

{
  "error": {
    "code": "conflict",
    "message": "The requested resource was not found.",
    "doc_url": "https://docs.codeqr.io/api-reference/errors#conflict"
  }
}

{
  "error": {
    "code": "invite_expired",
    "message": "The requested resource was not found.",
    "doc_url": "https://docs.codeqr.io/api-reference/errors#invite-expired"
  }
}

{
  "error": {
    "code": "unprocessable_entity",
    "message": "The requested resource was not found.",
    "doc_url": "https://docs.codeqr.io/api-reference/errors#unprocessable-entity"
  }
}

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "The requested resource was not found.",
    "doc_url": "https://docs.codeqr.io/api-reference/errors#rate-limit_exceeded"
  }
}

{
  "error": {
    "code": "internal_server_error",
    "message": "The requested resource was not found.",
    "doc_url": "https://docs.codeqr.io/api-reference/errors#internal-server_error"
  }
}

Overview

SDKs

APIs

Track a sale

Authorizations

Body

Response