Developer reference

JS API reference

The tracker exposes one function, paczesny.track(), for everything beyond automatic pageviews. This page documents its signature and the five commerce events the ingest endpoint validates and stores: view_item, add_to_cart, begin_checkout, purchase and refund.

Calling track()

Call paczesny.track() with an event name and a plain object of properties, once the tracker script has loaded. No configuration, no cookies and no consent banner are involved. Unknown property names are dropped server side, so sending extra keys is safe but pointless.

paczesny.track(name, props);

view_item

Send this when a shopper opens a product page. It rides the standard custom event pipe, so no order record is written: it is a funnel signal, not revenue.

Field	Type	Required	Description
itemId	string	Yes	Your product or SKU identifier. Trimmed, 1 to 128 characters.
itemName	string	No	Human readable product name, up to 256 characters.
priceMinor	integer, minor units	No	Unit price in integer minor units, for example 4999 for 49.99.
quantity	integer	No	Whole number of units. Must be positive.

paczesny.track("view_item", {
  itemId: "sku_123",
  itemName: "Wireless Mouse",
  priceMinor: 4999,
  quantity: 1,
});

add_to_cart

Send this when a shopper adds a product to the cart. Identical field shape to view_item, and like it, no order record is written.

Field	Type	Required	Description
itemId	string	Yes	Your product or SKU identifier. Trimmed, 1 to 128 characters.
itemName	string	No	Human readable product name, up to 256 characters.
priceMinor	integer, minor units	No	Unit price in integer minor units, for example 4999 for 49.99.
quantity	integer	No	Whole number of units. Must be positive.

paczesny.track("add_to_cart", {
  itemId: "sku_123",
  itemName: "Wireless Mouse",
  priceMinor: 4999,
  quantity: 2,
});

begin_checkout

Send this when a shopper enters checkout. Both fields are optional, so an empty properties object is still valid.

Field	Type	Required	Description
valueMinor	integer, minor units	No	Cart value in integer minor units, for example 9998 for 99.98.
itemCount	integer	No	Number of cart lines at checkout entry. Zero or more.

paczesny.track("begin_checkout", {
  valueMinor: 9998,
  itemCount: 2,
});

purchase

Send this once the order is confirmed, normally on the thank you page. It is the only event that writes a durable order record, so its fields are validated strictly and a float revenue is rejected rather than rounded.

Field	Type	Required	Description
orderId	string, max 128 chars	Yes	Your order identifier. It doubles as the idempotency key, so it must stay stable across reloads and payment retries.
revenue	integer, minor units	Yes	Order total in integer minor units. Floats are rejected, never rounded.
currency	ISO 4217 string	Yes	ISO 4217 code in uppercase, for example PLN or EUR. Lowercase codes are rejected.
items	array, max 20 items	No	Cart lines, each carrying id plus optional name, priceMinor, quantity and category. The first 20 lines are stored and the true line count is always kept.

paczesny.track("purchase", {
  orderId: "ORDER-1042",
  revenue: 9998,
  currency: "PLN",
  items: [
    {
      id: "sku_123",
      name: "Wireless Mouse",
      priceMinor: 4999,
      quantity: 2,
    },
  ],
});

refund

Send this to report a full or partial refund against an existing order. It nets out of revenue on the order's original day, never on the day the refund arrives, so a past day's totals are corrected rather than a later day being reduced.

Field	Type	Required	Description
orderId	string, max 128 chars	Yes	The same order identifier used on the original purchase event. An unknown orderId is rejected and logged, never silently accepted and never turned into a new order.
amountMinor	integer, minor units	No	The amount being refunded, in integer minor units. Omit this field entirely to refund the full remaining balance. Partial refunds accumulate, and an amount exceeding what remains is rejected and logged, never clamped.

paczesny.track("refund", {
  orderId: "ORDER-1042",
  amountMinor: 4999,
});

Order idempotency

Every purchase is stored under a key derived from your site and the orderId, backed by a unique index. Re-firing the same purchase after a page reload, a payment retry or a double click therefore never double counts revenue: the first write wins, and the later one is logged as a conflict instead of overwriting anything. Send the same orderId every time for the same order, and a different one only for a genuinely different order.

What is never stored

Field names are an allowlist, not a blocklist. Only the properties listed in the tables above are kept; anything else, including customer email, name, address, phone number or any custom key of your own, is stripped during validation and never reaches storage. Matching is exact and case sensitive, so EMAIL and Email are dropped just like email. Do not hide personal data inside an allowed field either: never use a shopper's email address as the orderId.

Integer minor units

revenue, priceMinor and valueMinor are always whole integers in the currency's smallest unit. 12999 means 129.99 in a two decimal currency such as PLN or EUR, and the number of decimals follows the currency, so a zero decimal currency such as JPY takes the plain amount. A float such as 129.99 is rejected and logged, never rounded, so the number you send is always the number stored.