# Browser Attribution API Reference

> Read visitor, session, landing-page, referrer, and UTM context in the browser before signup or checkout begins.

Canonical page: [https://attribiq.com/guides/browser-attribution-api](https://attribiq.com/guides/browser-attribution-api)

Category: API Reference

Last updated: 2026-09-04

Topics: browser api, attribution object, checkout, javascript

## Summary

The browser attribution API exposes the current AttribIQ project, visitor, session, landing page, referrer, and UTM context. Send this object to your backend when checkout starts.

## What this guide covers

- Read attribution from window.attribiq
- Understand the fields in the attribution object
- Send attribution safely to your backend
- Avoid trusting browser-provided data for billing decisions

The browser attribution API exposes the visit context that should travel into checkout.

Use it when a visitor clicks upgrade, starts checkout, creates a paid account, or begins any flow that can produce revenue.

## Read the object

```js
const attribution = window.attribiq.getAttribution()
```

Expected shape:

```json
{
  "project_id": "proj_123",
  "visitor_id": "v_abc",
  "session_id": "s_def",
  "landing_page": "/pricing",
  "referrer": "https://google.com",
  "utm_source": "google",
  "utm_campaign": "brand-search"
}
```

## Required fields

The minimum useful fields are:

- `project_id`
- `visitor_id`
- `session_id`

Landing page, referrer, and UTM values are useful for debugging, but the stable identifiers are what let AttribIQ join payment events to analytics sessions.

## Send attribution to your backend

```js
await fetch("/api/create-checkout-session", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    price_id: "price_123",
    attribution
  })
})
```

Your backend should validate the shape, ignore unknown fields, and decide which values to put into Stripe metadata or your own pending checkout record.

## Security boundaries

Do not use browser attribution to decide:

- Payment amount.
- Plan entitlement.
- Billing currency.
- User account ownership.
- Discount eligibility.

The browser attribution object is for reporting. Billing decisions belong on the server.

## Next steps

Use [pass attribution to Stripe Checkout](https://attribiq.com/guides/pass-attribution-to-stripe-checkout) for a full Stripe flow, or [Payment API reference](https://attribiq.com/guides/payment-api-reference) for custom billing.

## Frequently asked questions

### Can the browser attribution object be trusted?

Treat it as client-provided attribution context, not as billing authority. Validate shape and project ownership server-side.

### Which fields are required for revenue attribution?

project_id, visitor_id, and session_id are the minimum useful fields.

### Should I send the entire object to Stripe?

No. Send the object to your backend, then copy the stable identifiers into Stripe metadata.

### Can I store the object with my own checkout session?

Yes. Storing it with your own pending checkout record can make webhook reconciliation easier.