Manual mode

In manual mode, Quomerce sends only the commerce events your code reports, exactly as written. Nothing is detected.

qm("init", { key: "pk_live_…", commerce: "manual" });

When to call what

Make each call at the moment the thing happens. Use the call form, qm("commerce.<name>", …). It works before the script has loaded.

When	Call
A product page is shown	`qm("commerce.productViewed", product)`
A product is added to the cart	`qm("commerce.cartAdded", product, quantity)`
A product is removed from the cart	`qm("commerce.cartRemoved", product, quantity)`
The cart page is shown	`qm("commerce.cartViewed", cart)`
The buyer goes to checkout	`qm("commerce.checkoutStarted", cart)`
A shipping method is picked	`qm("commerce.shippingMethodSelected", "inpost_paczkomat")`
A payment method is picked	`qm("commerce.paymentMethodSelected", "blik")`
The buyer leaves for the payment gateway	`qm("commerce.paymentRedirected", "blik", "przelewy24")`
The buyer comes back from it	`qm("commerce.paymentReturned", "blik", "przelewy24", "success")`
A coupon is tried	`qm("commerce.couponApplied", code, accepted)`
The order confirmation is shown	`qm("commerce.purchase", order)`, once per order
A search runs	`qm("commerce.searchPerformed", term, resultCount)`
A category or other product list is shown	`qm("commerce.itemListViewed", { id, name }, productCount)`
A product is clicked in that list	`qm("commerce.itemSelected", product, { id, name }, index)`
A product goes on the wishlist	`qm("commerce.wishlistAdded", product)`
A banner is shown / clicked	`qm("commerce.promotionViewed", promotion)` / `qm("commerce.promotionSelected", promotion)`
An account is created / a buyer logs in	`qm("commerce.signedUp", "google")` / `qm("commerce.loggedIn", "email")`

The funnel uses six of these: product viewed, added to cart, checkout started, payment method chosen, went to payment, and order placed. Send at least those.

paymentReturned takes "success", "failure" or "unknown". Payment and shipping method names are free text, but keep them stable, such as "blik", "card", "transfer", "cod".

Data shapes

interface Product {
  id: string | number;         // your product id
  name: string;
  price: number;               // regular price, major units: 2899.99
  currency: string;            // ISO 4217: "PLN", "EUR"
  variantId?: string | number; // size, colour…
  sku?: string;
  url?: string;
  salePrice?: number;          // the price charged, if lower
  category?: string;
  brand?: string;
  image?: string;
  availability?: string;       // "in_stock", "out_of_stock"…
}

interface Cart {
  value: number;               // the cart's total
  currency: string;
  items: { product: Product; quantity: number }[];
}

interface Order {
  id: string | number;         // your order number
  value: number;               // the order's total
  currency: string;
  items?: { product: Product; quantity: number }[];
}

interface ItemList  { id?: string | number; name?: string }  // at least one
interface Promotion { id?: string | number; name?: string; creative?: string; slot?: string } // id or name

These types are in the TypeScript types file.

Example: an order confirmation

const order = {
  id: "ORD-1042",
  value: 3199.99,
  currency: "PLN",
  items: [{ product: { id: "gpu-1", name: "RTX 4070", price: 2899.99, currency: "PLN" }, quantity: 1 }],
};

// A reload of the confirmation page must not be a second order.
const key = `qm_purchase_${order.id}`;
if (!sessionStorage.getItem(key)) {
  qm("commerce.purchase", order);
  sessionStorage.setItem(key, "1");
}

The purchase call comes from the browser. A buyer who closes the tab on the payment page never sends it.

Calls after the script has loaded

Once the script has loaded, qm.commerce also has methods, such as qm.commerce.cartAdded(product, 1). They do the same thing. The call form is safer, because it also works before the script has loaded.