Skip to main content
A tracking link is a short link a creator shares off-platform. Every click is recorded as an impression, and once the visitor signs in, the click is attributed to their account. That gives you per-link click counts, the list of fans a link brought in, and their earnings. You can also attach your own key/value metadata to a click, so you can tie a fan back to the campaign, creative, or record in your own system that sent them.

​
Authentication Required

Tracking-link endpoints require OAuth with these scopes:
  • read:tracking_links - List links, list a link’s users, read a user’s metadata
  • write:tracking_links - Create and delete links
See the OAuth Tutorial for setup instructions.
The response contains the link’s uuid (which you use on the API) and its linkUrl (the short slug the creator shares):
The shareable URL is the creator’s handle followed by the slug:

​
Step 2: Attach your own metadata

Metadata is captured from the query string of the shared link. There is no API call and no field at creation time. Append your own parameters as plain query parameters, one per key:
Tracking links use plain query parameters (?campaign=spring_launch). They do not use the metadata[<key>]=<value> bracket syntax that checkout links use.
Every non-reserved parameter on the URL becomes a metadata entry. There is no prefix to add and no allowlist to register: utm_source, campaign, gclid and your own names are all treated the same way and captured as-is.

​
Step 3: Read the metadata back

Once the click is attributed to a fan, read it with the fan’s UUID:
Response behaviour: To find the fans to look up, use GET /tracking-links/{uuid}/users. Only clicks matched to an account appear there.

​
Limits

Metadata is sanitized at capture time. Nothing is rejected: over-limit input is silently trimmed, so a click is never lost because of its query string. If nothing valid remains, the click is still recorded and the metadata endpoint returns null.
Metadata is passthrough only: Fanvue never interprets it, and it is readable by anyone holding the creator’s read:tracking_links scope. Do not put secrets or personal data in it.

​
Overwrite semantics

Each click creates a new impression, and the metadata endpoint returns the metadata of the most recent click attributed to that fan on that link. Metadata is never merged across clicks.
  • A later click replaces the previous metadata wholesale. Keys present on the earlier click but absent from the later one are gone, not carried forward.
  • A later click with no query parameters at all returns "metadata": null. The earlier value is not preserved.
If you need the values to survive later visits, keep every parameter on every copy of the link you publish, or store the values in your own system the first time you read them.

​
Attribution timing

  • A click made while the visitor is signed in is attributed immediately.
  • A click made while signed out is recorded straight away, but stays unattributed until that visitor signs in from the same browser. Until then the metadata endpoint returns null for them.
  • A click made while signed in as the creator who owns the link is not recorded at all. Use a separate fan account when testing.

​
Metadata on webhooks

The new_follower and new_subscriber legacy events also carry the metadata of the fan’s most recent attributed click on any of the creator’s tracking links, as trackingLinkMetadata, alongside trackingLinkUrl. The sanitizing and most-recent-click rules above apply identically. Next: Tracking-link endpoints, or Checkout attribution for the equivalent on checkout links.