Skip to main content
Pass an optional BilyPayload to track(). Typed fields keep common data consistent, while additional top-level keys let you describe your application.

​
Build a payload

type BilyPayload = {
  client?: BilyClient;
  order?: BilyOrder;
  products?: BilyProduct[];
  pageTitle?: string;
  userAgent?: string;
  ip?: string;
  referrer?: string;
  sourceUrl?: string;
  source?: "app" | "web";
  category?: string;
  searchQuery?: string;
  eventAlias?: string;
  [key: string]: unknown;
};
The browser SDK sets source to web for you. For explicit SPA page views, send sourceUrl and pageTitle. For product searches, send searchQuery. Do not supply an IP address from browser code.

​
Describe a client

type BilyAddress = {
  city?: string;
  state?: string;
  zip?: string;
  country?: string;
};

type BilyClient = {
  firstname?: string;
  lastname?: string;
  dateOfBirth?: string;
  email?: string;
  phone?: string;
  gender?: string;
  address?: BilyAddress;
  userId?: string;
  userGroup?: string;
};
Every client field is optional. Send only the customer data allowed by the current consent state.

​
Describe a product

type BilyProduct = {
  id: string | number;
  name: string;
  price: number;
  currency: string;
  quantity?: number;
  sku?: string;
  category?: string;
  brand?: string;
  image?: string;
};
When you omit quantity, it defaults to 1. When you provide image, the SDK preserves it.

​
Describe an order

type BilyOrder = {
  id: string | number;
  products?: BilyProduct[];
  currency?: string;
  total?: number;
  tax?: number;
  discount?: number;
  discountCode?: string;
  shippingFees?: number;
};
If total is absent, the SDK calculates it from each product’s price and quantity. Zero remains valid for total, tax, discount, and shippingFees. When a payload contains order, place its products in order.products. Do not rely on the top-level products field for the same event.

​
Add application properties

Add your own top-level keys when an event needs application-specific properties. 
track("workspace_created", {
  workspace_id: "workspace_456",
  organization_id: "organization_789",
  plan: "growth",
});
The SDK creates event_id and ts when they are absent. Provide them yourself when you already have a stable event ID or timestamp. 
track("campaign_launched", {
  event_id: "campaign_launch_01J2M91S2P",
  ts: "2026-07-13T08:30:00.000Z",
  campaign_id: "campaign_123",
});

Event and data model

Ecommerce examples

Data safety