Event tracking by link: the Brevily events API

Report sign-ups and sales against the click that brought them: brv_click on the landing page, brv.js, and the events API with curl and Node.

On this page
  1. How event tracking by link works
  2. Turn on event tracking for a link
  3. Keep brv_click on your landing page
  4. Report an event from your server
  5. Report events from a web page with a website key
  6. List events and report many at once
  7. Troubleshooting event reports
  8. Common questions
  9. Next steps

Event tracking by link ties a sign-up, a sale or an install to the click that brought the visitor. Turn tracking on for a link, and every visit reaches your landing page with a brv_click value in the address. When the visitor signs up or buys, your server reports the event against that value with one call to the events API. No script is needed on the short link, and none on your site unless you want one.

Before you start: you need an API key with Integrations › Create, made under Access › API keys, and your organisation's code. See signing a request for both, and keep API errors open. Event tracking depends on your plan; see pricing.

  1. A tracked link adds brv_click to the destination. Its value is two ids joined by a dot: the click's, then the link's. It goes after the destination's own query, which is sent exactly as you stored it.
  2. Your site keeps the value with the visitor: read it on your server, or let the brv.js drop-in keep it in the browser.
  3. Something happens, and you report it. The event's name is in the address: sale, install, lead, or any name of your own. A sale, and any amount, comes from your server with a secret key. Other events may also come from a web page with a website key.

A visit to a tracked link lands like this, on one line:

https://example.com/autumn-sale?utm_source=newsletter&brv_click=01M3VC6VN1Q9X4T7B3N8C5V0R2.01M397JMN3X9T4R8N3C5V0W6YZ

Each event shows under Analytics › Events, by event and by link, with revenue per currency. It also goes to any webhook that chose Events, and to your GA4 streams.

In the console, open the link's Settings tab and switch on Track events; the create form has the same switch. Over the API, it's the link's trackConversions field, on create or later. Changing a link needs a key with Links › Edit.

bash
API=https://console.brevily.com/apiORG=EXAMPLE                       # your organisation's codeKEY=brv_ak_…                      # the key's IDSECRET=…                          # its secretLINK=01M397JMN3X9T4R8N3C5V0W6YZ   # the link's idcurl -X PATCH "$API/$ORG/links/$LINK" \  -H "x-api-key: $KEY" -H "x-api-secret: $SECRET" \  -H "content-type: application/json" \  -d '{"trackConversions": true}'

A 200 answers the link with "trackConversions": true. Within a few minutes, the destination opens with brv_click.

To test before your site is ready, open the short link in a browser, then read the click it made. This needs Analytics › View:

bash
curl "$API/$ORG/links/$LINK/clicks?size=25" \  -H "x-api-key: $KEY" -H "x-api-secret: $SECRET"

The newest click comes first. Its id, a dot and the link's id make the same value a visitor would carry.

Keep brv_click on your landing page

The value is only a query parameter on the first page the visitor lands on. The simplest way to keep it needs nothing from Brevily: read it on your server from the request and store it with the visitor, in your own cookie, their session or the sign-up record. No script runs, so no ad blocker can stop it. If the visitor comes back through another tracked link, keep the newest value.

Or use the brv.js drop-in

html
<script src="https://brevily.com/public/brv.js" async></script>

On every page it:

  • reads brv_click from the address, the newest one winning;
  • keeps it for the visit in the tab's sessionStorage, with no cookie;
  • takes it out of the address bar, so it isn't shared onwards;
  • fills any <input name="brv_click"> on the page, so a form posts it with the sign-up;
  • answers window.brv.click() with the value, and forgets it on window.brv.clear().

On its own it sends nothing anywhere: your server reads the form field and reports. To keep the value across visits, add data-remember-days="30" to the script tag, from 1 to 90 days. It then sets a first-party brv_click cookie on your own domain, so use it where your site's consent covers that cookie.

html
<form method="post" action="/signup">  <input type="email" name="email" required>  <input type="hidden" name="brv_click">  <button type="submit">Sign up</button></form>

Report an event from your server

Every report is a POST with a JSON body, the event's name at the end of the address. There are three addresses, depending on what you know about the visitor.

Against the click

Split the brv_click value at the dot: the click comes first, the link second.

bash
BRV_CLICK="01M3VC6VN1Q9X4T7B3N8C5V0R2.01M397JMN3X9T4R8N3C5V0W6YZ"   # as your page received itCLICK=${BRV_CLICK%.*}    # the part before the dotLINK=${BRV_CLICK#*.}     # the part after itcurl -X POST "$API/$ORG/links/$LINK/clicks/$CLICK/events/sale" \  -H "x-api-key: $KEY" -H "x-api-secret: $SECRET" \  -H "content-type: application/json" \  -d '{"amount": 4900, "currency": "EUR",       "id": "order_1042", "customer": "cust_8812"}'

A new event answers 201:

json
{  "id": "01M75Q8A1N3K2SQ24RZNHF0N9A",  "link": "01M397JMN3X9T4R8N3C5V0W6YZ",  "click": "01M3VC6VN1Q9X4T7B3N8C5V0R2",  "event": "sale",  "source": "SERVER",  "amount": 4900,  "currency": "EUR",  "customer": "cust_8812",  "properties": {},  "occurredAt": "2026-11-11T16:32:29.746Z",  "repeated": false}

Send the same id again and the answer is 200 with "repeated": true: the event is counted once.

The body's fields:

  • amount: whole minor units, so 4900 is 49.00. It needs currency, and a sale needs both.
  • currency: an ISO 4217 code such as EUR. Amounts are summed per currency, never converted.
  • id: your own id for the event, up to 128 characters, such as the order number. A report with an id already recorded counts once.
  • customer: your own id for the person, 1 to 128 characters with no spaces, never an email address. With a click, it binds that person to the click.
  • occurredAt: when it happened, in ISO 8601. Never in the future or before the click; left out, the time of the report.
  • properties: up to 15 names of your own with text, a number or true/false, such as {"plan": "pro"}. They travel with the event to webhooks and GA4. Never put personal data in them.

Without an id, a click counts each event name once, and a repeat updates its amount and time. Send an id whenever the same click can lead to several sales.

Against a link

When you know the link but not the click, for example a lead from a form with no brv_click, leave the click out of the address:

bash
curl -X POST "$API/$ORG/links/$LINK/events/lead" \  -H "x-api-key: $KEY" -H "x-api-secret: $SECRET" \  -H "content-type: application/json" \  -d '{"id": "form_5531", "properties": {"plan": "pro", "seats": 5}}'

Against the organisation, for first touch

Once a report has named a customer with a click, a later report may send the customer alone. It lands on that person's first reported click, so a renewal months later is still credited to the link that first brought them. A customer with no known click is recorded against no link.

bash
curl -X POST "$API/$ORG/events/renewal" \  -H "x-api-key: $KEY" -H "x-api-secret: $SECRET" \  -H "content-type: application/json" \  -d '{"customer": "cust_8812", "id": "order_1187",       "amount": 4900, "currency": "EUR"}'

Ids in the address always win: a link or click in the body is ignored.

The same report from Node

js
// Node 18 or later, on your server.const { API, ORG, KEY, SECRET } = process.env;// brvClick: the brv_click value you kept, or null when the visitor// didn't arrive through a tracked link.async function reportEvent(brvClick, name, body) {  const [click, link] = brvClick ? brvClick.split('.') : [];  const path = brvClick    ? `/links/${link}/clicks/${click}/events/${name}`    : `/events/${name}`;  const res = await fetch(`${API}/${ORG}${path}`, {    method: 'POST',    headers: {      'x-api-key': KEY,      'x-api-secret': SECRET,      'content-type': 'application/json',    },    body: JSON.stringify(body),  });  const answer = await res.json();  if (!res.ok) {    throw new Error(`${res.status} ${answer.code}: ${answer.message} (${answer.requestId})`);  }  return answer; // 201: a new event; 200: one it already had ("repeated": true)}// Once the order is paid:const event = await reportEvent(  '01M3VC6VN1Q9X4T7B3N8C5V0R2.01M397JMN3X9T4R8N3C5V0W6YZ',  'sale',  { amount: 4900, currency: 'EUR', id: 'order_1042', customer: 'cust_8812' },);console.log(event.id, event.repeated);

With no brv_click, the function reports to the organisation, so pass the customer and first touch does the rest.

Report events from a web page with a website key

A page can report a sign-up or an event of your own itself, with brv.js and a website key. A website key isn't a secret: it only sends events, only from the sites it lists, so it's safe in a web page. It never reports a sale or an amount; those come from your server, where nobody can change them.

  1. Open Link setup › Integrations and find Website key.
  2. Choose Add a website key.
  3. Under Site addresses, enter each site that will send events, one per line, such as https://shop.example.com.
  4. Give it a Label and choose Make key.

[screenshot: Link setup › Integrations, the Website key card with Add a website key and the tag to copy]

Making one needs API keys › Create, on a plan with website and app keys (see pricing). The card then shows the tag to put on your pages:

html
<script src="https://brevily.com/public/brv.js"  data-org="EXAMPLE"  data-key="brv_pk_…" async></script><script>  // after the sign-up succeeds  brv.track('signup', {    customer: 'cust_42',    dedupe: 'signup_42',    properties: { plan: 'pro', seats: 5 },  });</script>
  • It reports against the kept click when there is one, else against the organisation.
  • dedupe is your id for the event, so a reloaded page or a double tap counts once.
  • brv.track answers false when it sends nothing: no key, a sale, an amount, or a bad name.
  • A page's reports are deduplicated apart from your server's, so a page can never overwrite or block an event your server sent.

You can keep two live keys at once, for a change-over: put the new one on your pages, then Retire the old one.

List events and report many at once

GET /events reads them back, newest first, 25 a page, with Analytics › View. Narrow it with ?link=, ?event=, ?source=SERVER|DEVICE|WEB or ?range=7d|30d|90d, as far back as your plan keeps. The next page's cursor is the x-next-cursor header; send it back as ?before=.

bash
curl "$API/$ORG/events?link=$LINK" \  -H "x-api-key: $KEY" -H "x-api-secret: $SECRET"

To send a backlog, POST /events takes up to 100 rows, each naming its name, and its link and click where known:

bash
curl -X POST "$API/$ORG/events" \  -H "x-api-key: $KEY" -H "x-api-secret: $SECRET" \  -H "content-type: application/json" \  -d '[{"name": "sale", "link": "01M397JMN3X9T4R8N3C5V0W6YZ", "click": "01M3VC6VN1Q9X4T7B3N8C5V0R2",        "amount": 1500, "currency": "GBP", "id": "order_1050"},       {"name": "sale", "link": "01M397JMN3X9T4R8N3C5V0W6YZ", "id": "order_1051"}]'

The answer is a 200 with one result per row, in order. Each row is recorded or refused by itself:

[  { "status": 201, "event": { "id": "01M75QA4Z2E8JD33FEP87Y2GSK", "event": "sale", "amount": 1500, "currency": "GBP", "repeated": false, … } },  { "status": 400, "error": { "code": "VALIDATION_FAILED", "message": "A sale needs its amount and currency." } }]

Give every row an id, so sending the batch again after a failure records nothing twice.

Troubleshooting event reports

A refusal is the API's usual error body. The message says why:

  • 400 "A sale needs its amount and currency." or "An amount needs its currency.": send both, or neither for an event that isn't a sale.
  • 400 "The click is not this link's.": the two ids were swapped or taken from different values. The click comes before the dot.
  • 400 "The click is more than 90 days old.": a click can be reported against for 90 days from the visit. For later sales, report the customer alone.
  • 400 "occurredAt is before the click." or "occurredAt is in the future.": check the time and its zone.
  • 400 "Check the properties.": details.fields.properties names the property and the limit it broke.
  • 403 ACCESS_DENIED: the key lacks Integrations › Create (details.access says so), or your plan has no events.
  • 403 with details.reason: "events_limit_reached": the period's events, and any grace, are used. Send the refused ones again after the period resets or after an events top-up on Billing; each still counts once.
  • 404 "No such link." or "No such click.": the id isn't your organisation's. Check the organisation code and the value.
  • 429: too many reports in a minute. Wait Retry-After seconds and send again with the same id.

Event reports have their own rate-limit count, apart from your other API calls, so reporting every sale never uses up the room for your link calls. A website key has its own limit too. Reads such as GET /events count with your other calls.

Every call is in the API reference, with its fields and answers.

Common questions

Do I need brv.js for Brevily event tracking?

No. Your server can read brv_click from the landing page's address and keep it, with nothing running in the visitor's browser. brv.js saves you storing the value yourself, and lets a page report events with a website key.

Does Brevily event tracking change my destination's address?

Only by adding one brv_click pair at the end. The destination's own query, UTM tags included, is sent exactly as stored.

Is it safe to retry a Brevily event report?

Yes, if the report carries an id. A report whose id is already recorded answers 200 with "repeated": true and counts nothing new.

How long after a click can I report an event against it?

Up to 90 days from the visit; after that, a report against the click answers 400. For a later sale or renewal, report the customer alone, and it lands on that customer's first reported click.

How long does Brevily keep reported events?

For as long as your plan keeps them (see pricing), or fewer days if an admin sets Keep events for (days) under Settings › General › Events. First touch reaches back only as far.

Next steps

All developer guides

Brevily is invite-only, for now

Say what you would use it for and a person replies. Already invited? Sign in.