Features

Ecommerce

Track the complete purchase journey — product views, cart activity, checkout steps, completed orders, refunds, wishlists, and SaaS subscriptions — all with one-line fg.track() calls, the recommended way to send ecommerce events.

Overview

Every ecommerce event is sent through fg.track() on the fg instance you created in the SDK Quickstart. The key payload types you'll use:

types.ts

import type { Product, Cart, CartItem, Order } from "flowgrid-sdk/types";

// Product — used in views, cart adds, impressions
const product: Product = {
  productId: "sku_shirt_blue_L",
  name:      "Classic T-Shirt",
  price:     29.99,
  currency:  "USD",
  category:  "apparel/tops",
  variant:   "Blue / L",
  quantity:  1,
};

// CartItem extends Product + adds quantity + lineTotal
const cartItem: CartItem = { ...product, quantity: 2, lineTotal: 59.98 };

// Order — passed to purchases.complete()
const order: Order = {
  orderId:       "ord_abc123",
  items:         [cartItem],
  subtotal:      59.98,
  discountTotal: 0,
  shippingTotal: 5.00,
  taxTotal:      4.80,
  total:         69.78,
  currency:      "USD",
};

Tip

Every event below also has an equivalent typed namespace shortcut (fg.cart.add(), fg.purchases.complete(), …) that produces an identical payload. Prefer fg.track()— it's one consistent API across the whole SDK.

Product views & impressions

Track when a user opens a product detail page, when a product appears in a list, and when they click a product in a list.

products.ts

import { fg } from "@/lib/flowgrid";

// Product detail page opened
await fg.track("product_view", {
  productId: "sku_shirt_blue_L",
  name:      "Classic T-Shirt",
  price:     29.99,
  currency:  "USD",
  category:  "apparel/tops",
});

// Products appeared in a list (e.g. search results, category page)
await fg.track("product_impression", {
  list: {
    listId:   "search-results",
    listName: "Search Results",
    products: [
      { productId: "sku_shirt_blue_L",  name: "Classic T-Shirt", price: 29.99, currency: "USD" },
      { productId: "sku_pants_black_M", name: "Chino Pants",     price: 59.99, currency: "USD" },
    ],
  },
});

// User clicked a product from the list
await fg.track("product_click", {
  productId: "sku_shirt_blue_L",
  name:      "Classic T-Shirt",
  price:     29.99,
  currency:  "USD",
  listId:    "search-results", // list ID
  position:  1,                // position in list
});

Cart

Track every cart mutation — adds, removals, quantity changes, and cart views.

cart.ts

import { fg } from "@/lib/flowgrid";

const shirt = {
  productId: "sku_shirt_blue_L",
  name:      "Classic T-Shirt",
  price:     29.99,
  currency:  "USD",
};

// Add to cart
await fg.track("add_to_cart", { ...shirt, quantity: 2, cartId: "cart_xyz" });

// Remove from cart
await fg.track("remove_from_cart", { ...shirt, quantity: 1, cartId: "cart_xyz" });

// Update quantity (2 → 3)
await fg.track("update_cart_item", {
  ...shirt, previousQuantity: 2, newQuantity: 3, cartId: "cart_xyz",
});

// Cart page opened
await fg.track("view_cart", {
  cart: {
    cartId:        "cart_xyz",
    items:         [{ ...shirt, quantity: 3, lineTotal: 89.97 }],
    subtotal:      89.97,
    discountTotal: 0,
    total:         89.97,
    currency:      "USD",
  },
});

Checkout

Track each stage of your checkout funnel to identify exactly where users drop off.

checkout.ts

import { fg } from "@/lib/flowgrid";

const cart = {
  cartId:        "cart_xyz",
  items:         [{ productId: "sku_shirt_blue_L", name: "Classic T-Shirt", price: 29.99, currency: "USD", quantity: 1, lineTotal: 29.99 }],
  subtotal:      29.99,
  discountTotal: 0,
  total:         29.99,
  currency:      "USD",
};

// User clicked "Proceed to checkout"
await fg.track("begin_checkout", { cart });

// User moved to the shipping step
await fg.track("checkout_step", { step: "shipping", stepNumber: 1, cart });

// User entered shipping details
await fg.track("add_shipping_info", {
  cart,
  shipping: {
    method:   "standard",
    carrier:  "fedex",
    cost:     5.00,
    currency: "USD",
    estimatedDays: 5,
  },
});

Purchase

Fire fg.track("purchase", …) once the order is confirmed — typically on the order-confirmation page or in a server-side webhook.

purchase.ts

import { fg } from "@/lib/flowgrid";

await fg.track("purchase", {
  order: {
    orderId:       "ord_abc123",
    items:         [{ productId: "sku_shirt_blue_L", name: "Classic T-Shirt", price: 29.99, currency: "USD", quantity: 1, lineTotal: 29.99 }],
    subtotal:      29.99,
    discountTotal: 0,
    shippingTotal: 5.00,
    taxTotal:      2.40,
    total:         37.39,
    currency:      "USD",
  },
});

Tip

For server-side confirmation (webhook from Stripe, Shopify, etc.), use a server-side FlowGrid instance so the event fires even when the user has closed the tab.

Wishlist

wishlist.ts

import { fg } from "@/lib/flowgrid";

const shirt = { productId: "sku_shirt_blue_L", name: "Classic T-Shirt", price: 29.99, currency: "USD" };

await fg.track("add_to_wishlist",      { ...shirt, wishlistId: "wl_abc" });
await fg.track("remove_from_wishlist", { ...shirt, wishlistId: "wl_abc" });
await fg.track("wishlist_to_cart",     { ...shirt, wishlistId: "wl_abc" });
await fg.track("share_wishlist",       { wishlistId: "wl_abc", method: "link" });

Subscriptions SaaS / recurring billing

Track the full SaaS subscription lifecycle — new plans, upgrades, downgrades, cancellations, renewals, and trial conversions.

subscriptions.ts

import { fg } from "@/lib/flowgrid";

// New subscription started
await fg.track("subscription_start", {
  subscriptionId: "sub_abc", userId: "u_123", plan: "pro",
  mrr: { amount: 79, currency: "USD" }, billingCycle: "monthly",
});

// Plan upgrade
await fg.track("subscription_change", {
  subscriptionId: "sub_abc", userId: "u_123",
  previousPlan: "pro", newPlan: "enterprise",
  previousMrr: { amount: 79, currency: "USD" },
  newMrr: { amount: 299, currency: "USD" },
  changeType: "upgrade",
});

// Cancellation (immediate: false = cancel at period end)
await fg.track("subscription_cancel", {
  subscriptionId: "sub_abc", userId: "u_123", plan: "enterprise",
  lostMrr: { amount: 299, currency: "USD" }, immediate: false,
});

// Trial → paid conversion
await fg.track("trial_converted", {
  subscriptionId: "sub_abc", userId: "u_123", plan: "pro",
  mrr: { amount: 79, currency: "USD" },
});

Full purchase flow

Putting it all together — every event from product view to order confirmation:

full-flow.ts

import { fg } from "@/lib/flowgrid";

const product = { productId: "sku_1", name: "T-Shirt", price: 29.99, currency: "USD" };
const cartId  = "cart_xyz";
const cart    = {
  cartId, currency: "USD",
  items: [{ ...product, quantity: 1, lineTotal: 29.99 }],
  subtotal: 29.99, discountTotal: 0, total: 29.99,
};

// 1. Product page opened
await fg.track("product_view", product);

// 2. Added to cart
await fg.track("add_to_cart", { ...product, quantity: 1, cartId });

// 3. Checkout began
await fg.track("begin_checkout", { cart });

// 4. Shipping entered
await fg.track("add_shipping_info", { cart, shipping: { method: "standard", carrier: "ups", cost: 5, currency: "USD", estimatedDays: 5 } });

// 5. Order confirmed (server-side preferred for reliability)
await fg.track("purchase", {
  order: {
    orderId: "ord_1", items: cart.items,
    subtotal: 29.99, discountTotal: 0, shippingTotal: 5, taxTotal: 2.40, total: 37.39,
    currency: "USD",
  },
});

All ecommerce events

Every event name you can pass to fg.track(), grouped by area.

Area	Covers	Event names
Products	Product views, list impressions, list clicks	product_view, product_impression, product_click
Cart	Add, remove, update, view cart	add_to_cart, remove_from_cart, update_cart_item, view_cart
Checkout	Begin checkout, steps, shipping, payment	begin_checkout, checkout_step, add_shipping_info
Purchase	Completed orders	purchase
Refunds	Full or partial refunds	refund, refund_requested, refund_approved, refund_denied, refund_completed
Wishlist	Add, remove, view, move to cart, share	add_to_wishlist, remove_from_wishlist, view_wishlist, wishlist_to_cart, share_wishlist
Subscriptions	SaaS plan lifecycle	subscription_start, subscription_change, subscription_cancel, subscription_renew, trial_converted, trial_expired
Promotions	Coupon & promotion views / applications	promotion_view, promotion_click, coupon_used

PreviousFeature Usage Next A/B Experiments

On this page

Overview
Product views
Cart
Checkout
Purchase
Wishlist
Subscriptions (SaaS)
Full purchase flow
All events

Getting Started

Tracking Campaigns