Track Sale - taap.it API

Endpoint

POST https://track.taap.it/api/events/sale

Authentication

Server-side (Recommended)
Client-side

Use your secret API key:

Authorization: Bearer taapit_sk_xxxxxxxxxxxx

Use your publishable key:

X-Publishable-Key: taapit_pk_xxxxxxxxxxxx

Request Body

Field	Type	Required	Description
`trackingId`	string	✓	The `ta_tid` from the cookie or URL parameter
`customer`	object	✓	Customer information
`customer.externalId`	string	✓	Your internal user/customer ID
`customer.email`	string		Customer’s email address
`customer.firstname`	string		Customer’s first name
`customer.lastname`	string		Customer’s last name
`customer.phoneNumber`	string		Customer’s phone number
`customer.avatarUrl`	string		URL to customer’s avatar image
`amount`	number	✓	Transaction amount in currency units (not cents)
`currency`	string	✓	ISO 4217 currency code (e.g., `eur`, `usd`)
`metadata`	object		Additional custom data (key-value pairs)

Amount format: Use currency units, not cents.

✅ 29.99 for €29.99
❌ 2999 would be interpreted as €2999

Examples

cURL
Node.js SDK
React Hook
JavaScript

curl -X POST https://track.taap.it/api/events/sale \
  -H "Authorization: Bearer taapit_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "trackingId": "rLnWe1uz9t282v7g",
    "customer": {
      "externalId": "user_123",
      "email": "john@example.com"
    },
    "amount": 99.99,
    "currency": "eur",
    "metadata": {
      "orderId": "order_456",
      "plan": "pro"
    }
  }'

import { Taapit } from 'taapit-sdk';

const taapit = new Taapit({
  apiKey: process.env.TAAPIT_API_KEY,
});

await taapit.track.sale({
  trackingId: 'rLnWe1uz9t282v7g',
  customer: {
    externalId: 'user_123',
    email: 'john@example.com',
  },
  amount: 99.99,
  currency: 'eur',
  metadata: {
    orderId: 'order_456',
    plan: 'pro',
  },
});

import { useTaapitAnalytics } from 'taapit-sdk/react';

function CheckoutButton({ order }) {
  const { trackSale } = useTaapitAnalytics();

  const handlePurchase = async () => {
    trackSale({
      customer: {
        externalId: order.userId,
        email: order.email,
      },
      amount: order.total,
      currency: 'eur',
      metadata: {
        orderId: order.id,
        plan: order.plan,
      },
    });
  };
}

<script src="https://taap.it/api/sdk" data-publishable-key="taapit_pk_xxx"></script>

<script>
  taapit.trackSale({
    customer: {
      externalId: 'user_123',
      email: 'john@example.com',
    },
    amount: 99.99,
    currency: 'eur',
    metadata: {
      orderId: 'order_456',
    },
  });
</script>

Response

200 OK
400 Bad Request
401 Unauthorized
404 Not Found

{
  "ok": true
}

{
  "error": "Invalid payload",
  "details": [
    {
      "path": ["amount"],
      "message": "Required"
    }
  ]
}

{
  "error": "Invalid API key"
}

{
  "error": "Click not found for this trackingId"
}

Currency Codes

Use standard ISO 4217 currency codes:

Currency	Code
Euro	`eur`
US Dollar	`usd`
British Pound	`gbp`
Japanese Yen	`jpy`
Swiss Franc	`chf`
Canadian Dollar	`cad`
Australian Dollar	`aud`

Error Codes

HTTP Code	Error	Description
400	`Invalid payload`	Request body validation failed
400	`Missing customer.externalId`	Required field not provided
401	`Invalid API key`	API key is invalid or revoked
401	`Hostname not in allowed list`	Origin not whitelisted (client-side)
403	`This click does not belong to your workspace`	trackingId is for a different workspace
404	`Click not found for this trackingId`	trackingId doesn’t exist or has expired

​Endpoint

​Authentication

​Request Body

​Examples

​Response

​Currency Codes

​Error Codes

Endpoint

Authentication

Request Body

Examples

Response

Currency Codes

Error Codes