tracker.trackRefund()

Fires a GA4 refund event. Always GA4-only — conversionLabels.refund does not exist; Ads refund adjustments use a different API endpoint (uploadConversionAdjustments) that the SDK does not implement in v1.

Signature

tracker.trackRefund(input: BrowserRefundInput): Promise<void>;

BrowserRefundInput

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

Field	Required	Notes
transactionId	yes	Must match the original trackPurchase transactionId so GA4 ties the refund to the right purchase.
value	no	Refund amount in currency. Omit for full refunds (GA4 infers from transactionId).
currency	no	ISO 4217. Required by GA4 when value is set.
items	no	TrackbridgeItem[] for partial refunds — pass the items being refunded.
affiliation, coupon, shipping, tax	no	Forwarded as GA4 params.
userData	no	Hashed per enhanced conversions when supplied.

Returns

Promise<void>.

Errors

Throws synchronously if transactionId is missing or empty.

Example

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

await tracker.trackRefund({
  transactionId: order.id,
  value: refundAmount,
  currency: order.currency,
  items: refundedLines.map((line) => ({
    itemId: line.sku,
    quantity: line.quantity,
  })),
});

Browser-side refunds are uncommon in practice — refunds usually originate from an admin panel or a payment-provider webhook. The server-side serverTracker.trackRefund() is the more common call site.

See also

• serverTracker.trackRefund() — the more common entry point.
• Semantic helpers — why refund Ads is intentionally out of scope.