tracker.trackPurchase()

Fires a GA4 purchase event from the browser. When conversionLabels.purchase is configured on createBrowserTracker, also fires the matching Ads conversion in the same call, sharing the transactionId with the eventual server-side counterpart for dedup.

Signature

tracker.trackPurchase(input: BrowserPurchaseInput): Promise<void>;

`BrowserPurchaseInput`

type BrowserPurchaseInput = {
  transactionId: string;
  value: number;
  currency: string;
  items: TrackbridgeItem[];
  affiliation?: string;
  coupon?: string;
  shipping?: number;
  tax?: number;
  userData?: UserData;
};

Field	Required	Notes
`transactionId`	yes	The dedup key. No auto-generation — purchase is the canonical dual-fire conversion, so a missing ID is treated as a programming error.
`value`	yes	Conversion value in `currency`.
`currency`	yes	ISO 4217 (e.g. `'USD'`).
`items`	yes	Typed `TrackbridgeItem[]`. Empty arrays are sent as `[]` (GA4 distinguishes empty from absent). See `TrackbridgeItem`.
`affiliation`	no	Forwarded as GA4 `affiliation` param.
`coupon`	no	Forwarded as GA4 `coupon` param.
`shipping`	no	Forwarded as GA4 `shipping` param.
`tax`	no	Forwarded as GA4 `tax` param.
`userData`	no	Pass raw — the SDK normalizes and SHA-256 hashes per enhanced conversions.

Returns

Promise<void>. Resolves after the gtag pushes have been queued. Like trackConversion, gtag failures are caught and logged via console.warn only when debug: true.

Behavior

If conversionLabels.purchase is configured and userData is supplied, calls gtag('set', 'user_data', { ... }) with hashed PII.
If conversionLabels.purchase is configured, calls gtag('event', 'conversion', { send_to: '${adsConversionId}/${conversionLabels.purchase}', transaction_id, value, currency }).
Always calls gtag('event', 'purchase', { transaction_id, value, currency, items, affiliation?, coupon?, shipping?, tax? }) for GA4.
items is mapped from camelCase (itemId) to snake_case (item_id) by the same routine used on the server, byte-identically.

Errors

Throws synchronously if transactionId is missing or empty. No auto-generation for purchases.

Example

'use client';
import { useEffect } from 'react';
import { tracker } from '@/lib/tracker.client';

export function FirePurchase({ order }: { order: Order }) {
  useEffect(() => {
    tracker.trackPurchase({
      transactionId: order.id,
      value: order.total,
      currency: order.currency,
      items: order.items.map((line) => ({
        itemId: line.sku,
        itemName: line.name,
        price: line.unitPrice,
        quantity: line.quantity,
      })),
      coupon: order.couponCode,
      userData: {
        email: order.customer.email,
      },
    });
  }, [order]);
  return null;
}