> ## Documentation Index
> Fetch the complete documentation index at: https://learn.biq.li/llms.txt
> Use this file to discover all available pages before exploring further.

# Server tracking quickstart

> Send trusted leads and sales from your backend.

Server tracking is the recommended path for events your backend can verify, especially payments, subscriptions, renewals, and account creation.

## Before you start

1. Open **Workspace settings -> Tracking** and enable conversion tracking.
2. Open **Workspace settings -> API Keys**.
3. Create a **Restricted** key with **Conversions -> Write**.
4. Store the `biqli_...` key in a server secret or environment variable.
5. Capture the browser's `bq_id` during signup or checkout.

```bash theme={null}
BIQLI_API_KEY=biqli_xxxxxxxxxxxxxxxxxxxxxxxx
```

<Warning>
  Never return this key to a browser or place it in a client bundle, URL, cookie, public repository, screenshot, or log.
</Warning>

## TypeScript and Node.js

```bash theme={null}
npm install @biqli/sdk
```

```ts theme={null}
import {Biqli} from '@biqli/sdk';

const biqli = new Biqli({
  apiKey: process.env.BIQLI_API_KEY!,
});

await biqli.track.lead({
  clickId: request.cookies.bq_id,
  eventId: `signup:${customer.id}`,
  eventName: 'Signed up',
  customerExternalId: customer.id,
});
```

## PHP

```bash theme={null}
composer require biqli/sdk
```

```php theme={null}
use Biqli\Sdk\Biqli;

$biqli = new Biqli($_ENV['BIQLI_API_KEY']);

$biqli->track->sale([
    'clickId' => $_COOKIE['bq_id'] ?? null,
    'customerExternalId' => (string) $customer->id,
    'amount' => 4999,
    'currency' => 'usd',
    'paymentProcessor' => 'stripe',
    'invoiceId' => $invoice->id,
]);
```

## Forward the click ID safely

Read `bq_id` in the browser and associate it with the authenticated signup, checkout, or customer session on your server. Do not accept a browser-supplied customer owner ID without authenticating it.

After Biqli has attributed that customer, later events may omit `clickId` and use the same `customerExternalId`.

## Retry safely

Official server SDKs retry temporary network errors and retryable HTTP responses with bounded backoff.

* Give each lead a stable `eventId`.
* Give each sale a stable `paymentProcessor` and `invoiceId`.
* Keep the payload identical across retries.

Do not create a new identifier on every attempt.

## Confirm the event

Open **Customers**, select the matching customer, and confirm the timeline shows the expected click, lead or sale, attribution link, amount, and source.