serverTracker.trackRefund()

Server-side refund. The common entry point for refunds — most refunds originate from an admin panel or a payment-provider webhook, not from the browser.

GA4-only by design. The ads destination always returns { skipped: true, reason: 'refund_ads_unsupported' }. Ads refund adjustments use a different API endpoint (uploadConversionAdjustments) that the SDK does not implement in v1.

Signature

serverTracker.trackRefund(input: ServerRefundInput): Promise<ServerHelperResult>;

ServerRefundInput

type ServerRefundInput = {
  transactionId: string;
  value?: number;
  currency?: string;
  items?: TrackbridgeItem[];
  affiliation?: string;
  coupon?: string;
  shipping?: number;
  tax?: number;
  clientId: string;
  userId?: string;
  userData?: UserData;
  consent?: ServerConsent;
};

Field	Required	Notes
transactionId	yes	Must match the original trackPurchase transactionId.
clientId	yes	GA4 client ID — typically the value persisted on the order row at checkout.
value	no	Refund amount. Omit for a full refund (GA4 infers from transactionId).
currency	no	ISO 4217. Required by GA4 when value is set.
items	no	Items being refunded — for partial refunds.
affiliation, coupon, shipping, tax	no	GA4 params.
userId, userData, consent	no	Standard.

Returns

Promise<ServerHelperResult>. The ads field is always:

{ skipped: true, reason: 'refund_ads_unsupported' }

The ga4 field carries { ok } | { ok: false, error }.

Example

export async function POST(req: Request) {
  const event = await verifyStripeSignature(req);
  if (event.type !== 'charge.refunded') return new Response();

  const order = await db.orders.findByChargeId(event.data.object.id);

  const result = await serverTracker.trackRefund({
    transactionId: order.id,
    value: event.data.object.amount_refunded / 100,
    currency: order.currency,
    clientId: order.gaClientId,
  });

  if (!result.ga4.ok && !('skipped' in result.ga4)) reportError(result.ga4.error);
  return new Response();
}

See also

• tracker.trackRefund()
• Semantic helpers — why refund Ads is intentionally out of scope.