Event reference
Send the names exactly as written. Property names are snake_case throughout. Anything not marked required is optional, and extra properties of your own are fine — they are stored alongside the rest.
You do not need all thirty. Most stores send five: Product Viewed, Product Added, Checkout Started, Order Completed and Products Searched.
The product object
Several events carry a products array. Every entry uses the same shape:
{
product_id: "P-4471", // required
sku: "WH-BLK-01",
name: "Wireless Headphones",
price: 199.99,
quantity: 1,
currency: "SAR",
category: "Electronics",
brand: "AudioTech",
variant: "Black",
position: 3,
coupon: "SUMMER20",
url: "https://store.example.com/p/headphones",
image_url: "https://store.example.com/i/headphones.jpg"
}
price and quantity are worth filling in even where they are optional: when an order arrives without a total, Flowfy rebuilds revenue by summing price × quantity across the array.
Money
| Property | Meaning |
|---|---|
value | What the order is worth. This is the revenue field |
currency | Three-letter code — SAR, USD |
subtotal | Before shipping, tax and discount |
discount | Amount taken off |
shipping | Shipping charged |
tax | Tax charged |
Send value on anything carrying money; revenue is accepted as a synonym. Always send currency beside it — an amount with no currency cannot be compared against ad spend.
Browsing
| Event | Required | Also useful |
|---|---|---|
Products Searched | query | results_count, products |
Product List Viewed | products, and one of list_id / list_name / category | — |
Product List Filtered | filters | list_id, list_name, category, sorts, products |
Product Viewed | product_id | every product field |
Product Clicked | product_id | product fields, list_id, list_name |
filters is an array of { type, value }. sorts is an array of { field, direction }, where direction is asc or desc.
flowfyanalytics.track("Product Viewed", {
product_id: "P-4471",
name: "Wireless Headphones",
price: 199.99,
currency: "SAR",
category: "Electronics"
});
Promotions
| Event | Required | Also useful |
|---|---|---|
Promotion Viewed | promotion_id, name | creative, placement, position |
Promotion Clicked | promotion_id, name | creative, placement, position |
Cart and checkout
| Event | Required | Also useful |
|---|---|---|
Product Added | product_id, quantity | product fields, cart_id, source |
Product Removed | product_id, quantity | product fields, cart_id |
Cart Viewed | cart_id, products | currency, value |
Checkout Started | checkout_id, currency, value, products | subtotal, discount, shipping, tax, cart_id, coupon |
Checkout Step Viewed | checkout_id, step | step_name, payment_method, shipping_method |
Checkout Step Completed | checkout_id, step | step_name, payment_method, shipping_method |
Payment Info Entered | checkout_id, payment_method | order_id, shipping_method, step |
step is a whole number starting at 1. source on Product Added says where it came from: product_page, wishlist, search, listing, recommendation or other.
flowfyanalytics.track("Checkout Started", {
checkout_id: "CHK-8821",
currency: "SAR",
value: 523.17,
subtotal: 489.98,
shipping: 22.00,
tax: 11.19,
products: [
{ product_id: "P-4471", name: "Wireless Headphones", price: 199.99, quantity: 1 },
{ product_id: "P-2210", name: "Phone Case", price: 145.00, quantity: 2 }
]
});
Orders
| Event | Required | Also useful |
|---|---|---|
Order Completed | order_id, currency, value, products | subtotal, discount, shipping, tax, checkout_id, coupon, payment_method, shipping_method |
Order Updated | order_id, previous_status, current_status, changed_fields | money fields, products |
Order Refunded | refund_id, order_id, refund_amount, currency | reason, products |
Order Cancelled | order_id, currency, value | cancellation_reason, previous_status, products |
Order Completed is the one event worth getting exactly right — it is what every advertising platform optimises against.
flowfyanalytics.track("Order Completed", {
order_id: "ORD-12345",
currency: "SAR",
value: 523.17,
subtotal: 489.98,
shipping: 22.00,
tax: 11.19,
coupon: "SUMMER20",
payment_method: "mada",
products: [
{ product_id: "P-4471", name: "Wireless Headphones", price: 199.99, quantity: 1 },
{ product_id: "P-2210", name: "Phone Case", price: 145.00, quantity: 2 }
]
});
order_id is what makes an order one order. Without it Flowfy cannot tell a repeated event from a second purchase, so duplicates are counted twice. transaction_id is accepted in its place. An order_id of 0 is treated as missing.
For a partial refund, send only the returned lines and the amount actually refunded. For a full refund the products array can be left out.
Coupons
| Event | Required |
|---|---|
Coupon Entered | coupon, and one of cart_id / checkout_id / order_id |
Coupon Applied | coupon, and one of cart_id / checkout_id / order_id |
Coupon Denied | coupon, reason, and one of cart_id / checkout_id / order_id |
Coupon Removed | coupon, and one of cart_id / checkout_id / order_id |
coupon is the code the shopper typed. coupon_id, coupon_name and discount are optional.
Wishlist
| Event | Required | Also useful |
|---|---|---|
Product Added to Wishlist | product_id, wishlist_id | product fields, wishlist_name |
Product Removed from Wishlist | product_id, wishlist_id | product fields, wishlist_name |
Note the lower-case to and from in those two names.
When a shopper moves something from a wishlist into the cart, send Product Added with source: "wishlist".
Sharing
| Event | Required | Also useful |
|---|---|---|
Product Shared | product_id, share_via | product fields, recipient, share_message |
Cart Shared | cart_id, products, share_via | recipient, share_message |
WhatsApp Clicked | href | target_phone, source, element_id, page_url, page_title |
share_via is one of email, whats_app, sms, social, link, other. On Cart Shared, each entry in products needs only product_id.
Reviews
| Event | Required | Also useful |
|---|---|---|
Product Reviewed | product_id, review_id, rating | review_body |
rating is a whole number from 1 to 5.
Leads and forms
| Event | Required | Also useful |
|---|---|---|
Lead | lead_source | lead_id, contact_method, form_id, status, estimated_value, currency |
Form Submitted | form_id | form_name, action, status, fields, locale, url |
lead_source is one of contact_form, lead_form, whats_app, phone, live_chat, quote_request, callback_request, newsletter, other.
Do not put a shopper's name, email or phone into Lead properties. Send them through identify instead, where they are hashed before being forwarded.
Which events count as conversions
These are treated as conversions in reporting: Order Completed, Checkout Completed, Purchase, Lead, Sign Up, Form Submitted, Contact, CompleteRegistration.
Of those, only Order Completed, Checkout Completed and Purchase carry revenue. A Lead that happens to include a products array will never have that array summed into your revenue — which is what keeps cost-per-lead honest.