> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cabrapi.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Affiliate Script

> Install the click tracking script to attribute visits and sales to your affiliates.

# Affiliate Tracking Script

The caBRAPI `clicks.js` script tracks affiliates' clicks and visits to your store. When a visitor accesses with `?ref=` in the URL, the script registers the click and saves the affiliate code in a cookie for future attribution.

## How it works

1. The affiliate shares a link like `https://sualoja.com/?ref=CODIGO`
2. The visitor accesses the link
3. The script detects `?ref=`, saves the `affiliate_id` cookie and sends the click to the API
4. Even if the visitor browses to other pages without `?ref=`, the cookie keeps attributing visits to the affiliate
5. If the visitor makes a purchase, checkout sends the affiliate code for commission

## Installation

Add the script **before `</body>`** in your HTML page:

```html theme={null}
<script
  src="https://www.cabrapi.com.br/script/clicks.js"
  data-store="ID_DA_LOJA"
  data-api="https://api.cabrapi.com.br"
  data-days="30"
></script>
```

## Parameters

| Attribute | Required | Description | Default |
| - | - | - | - |
| `data-store` | Yes | Your store ID in caBRAPI | — |
| `data-api` | No | caBRAPI API URL | `https://api.cabrapi.com.br` |
| `data-days` | No | Cookie lifetime in days | `30` |

## Complete example

```html theme={null}
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <title>My Store</title>
</head>
<body>
  <h1>Welcome to my store</h1>

  <!-- Your content -->

  <!-- Affiliate tracking script -->
  <script
    src="https://www.cabrapi.com.br/script/clicks.js"
    data-store="abc123"
    data-api="https://api.cabrapi.com.br"
    data-days="30"
  ></script>
</body>
</html>
```

## Accepted link formats

The script detects the affiliate by any of these formats:

| Format | Example |
| - | - |
| Query parameter | `?ref=CODIGO` |
| Hash parameter | `#ref=CODIGO` |
| Path prefix `/r/` | `/r/CODIGO` |
| Path prefix `/ref/` | `/ref/CODIGO` |
| Path prefix `/aff/` | `/aff/CODIGO` |
| Path prefix `/afiliado/` | `/afiliado/CODIGO` |

The affiliate code must be between 2 and 64 characters (letters, numbers, `_` or `-`).

## Cookie

* **Name:** `affiliate_id`
* **Duration:** 30 days (or the value defined in `data-days`)
* **Property:** `SameSite=Lax`, `path=/`
* The cookie is updated whenever a new `?ref=` is detected

## Checkout (purchase attribution)

For checkout to attribute the purchase to the affiliate, read the `affiliate_id` cookie at payment time:

```javascript theme={null}
function getAffiliateId() {
  const m = document.cookie.match(/(?:^|; )affiliate_id=([^;]*)/);
  if (!m) return null;
  try {
    return decodeURIComponent(m[1]);
  } catch {
    return m[1];
  }
}

// Send in the payment payload
const affiliateId = getAffiliateId();
if (affiliateId) {
  // Include in the metadata.affiliate field of the payment
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.