# Commerce & Catalog Item Events This guide explains how to send commerce and catalog-related user interactions to Pushly using the Web SDK. These events power features like abandoned cart notifications, saved item reminders, revenue attribution, and catalog-driven recommendation campaigns. The Pushly Web SDK must be loaded and initialized before sending any of the events described below. {% hint style="info" %} The following steps assume that you are providing an item catalog/feed to our team. Please contact your account manager for more information on this process. {% endhint %} ### Supported Interaction Types Pushly supports the following commerce and catalog interactions: * **view\_item** – A user views an item detail page * **save\_item** – A user saves or favorites an item * **unsave\_item** – A user removes saved or unfavorites an item * **complete\_item** – A user completes an item * **uncomplete\_item** – A user removes completed item * **rate\_item** – A user rates an item * **unrate\_item** – A user removes rating from an item * **add\_to\_cart** – A user adds an item to their cart * **update\_cart** – A user modifies cart contents or quantities * **purchase** – A user completes a transaction Each interaction can reference items using one of three identifier types, depending on your catalog configuration. ### Item Identifier Types Every interaction includes one of the following top‑level arrays: * **products** – Standard e‑commerce product catalog items * **events** – Event‑based catalog items (e.g., ticketed content) * **recipes** – Recipe or content‑based catalog items Only one identifier type should be included per interaction call. Each item requires an `id`. Quantity is optional unless otherwise noted. {% hint style="danger" %} All of the following code snippets must be ran **after** the SDK has been initialized. {% endhint %} ### View Item Send this event when a user views an item detail page. {% tabs %} {% tab title="Products" %} ``` pushly('view_item', { "products": [ { "id": "PRODUCT_ID" } ] }); ``` {% endtab %} {% tab title="Events" %} ``` pushly('view_item', { "events": [ { "id": "EVENT_ID" } ] }); ``` {% endtab %} {% tab title="Recipes" %} ``` pushly('view_item', { "recipes": [ { "id": "RECIPE_ID" } ] }); ``` {% endtab %} {% endtabs %} ### Save Item Use this event when a user saves, favorites, or bookmarks an item. This enables saved‑item reminder campaigns. {% tabs %} {% tab title="Products" %} ``` pushly('save_item', { "products": [ { "id": "PRODUCT_ID" } ] }); ``` {% endtab %} {% tab title="Events" %} ``` pushly('save_item', { "events": [ { "id": "EVENT_ID" } ] }); ``` {% endtab %} {% tab title="Recipes" %} ``` pushly('save_item', { "recipes": [ { "id": "RECIPE_ID" } ] }); ``` {% endtab %} {% endtabs %} ### Unsave Item Use this event when a user removes an item from the saved list, favorites, or bookmarks. {% tabs %} {% tab title="Products" %} ``` pushly('unsave_item', { "products": [ { "id": "PRODUCT_ID" } ] }); ``` {% endtab %} {% tab title="Events" %} ``` pushly('unsave_item', { "events": [ { "id": "EVENT_ID" } ] }); ``` {% endtab %} {% tab title="Recipes" %} ``` pushly('unsave_item', { "recipes": [ { "id": "RECIPE_ID" } ] }); ``` {% endtab %} {% endtabs %} ### Complete Item A user marks an item as completed after finishing its intended experience. {% tabs %} {% tab title="Products" %} ``` pushly('complete_item', { "products": [ { "id": "PRODUCT_ID" } ] }); ``` {% endtab %} {% tab title="Events" %} ``` pushly('complete_item', { "events": [ { "id": "EVENT_ID" } ] }); ``` {% endtab %} {% tab title="Recipes" %} ``` pushly('complete_item', { "recipes": [ { "id": "RECIPE_ID" } ] }); ``` {% endtab %} {% endtabs %} ### Uncomplete Item Use this event to revert the completion of an item. {% tabs %} {% tab title="Products" %} ``` pushly('uncomplete_item', { "products": [ { "id": "PRODUCT_ID" } ] }); ``` {% endtab %} {% tab title="Events" %} ``` pushly('uncomplete_item', { "events": [ { "id": "EVENT_ID" } ] }); ``` {% endtab %} {% tab title="Recipes" %} ``` pushly('uncomplete_item', { "recipes": [ { "id": "RECIPE_ID" } ] }); ``` {% endtab %} {% endtabs %} ### Rate Item The `rate_item` event includes an optional `rating` property.\ If provided, `rating` must be a numeric value between **0 and 100** inclusive, with **up to 1 decimal place**. Integer values are valid.\ If `rating` is omitted, the event is valid.\ Invalid `rating` values causes the SDK to **reject the event and not send it**. {% tabs %} {% tab title="Products" %} ``` pushly('rate_item', { "products": [ { "id": "PRODUCT_ID", "rating": 5, } ] }); ``` {% endtab %} {% tab title="Events" %} ``` pushly('rate_item', { "events": [ { "id": "EVENT_ID", "rating": 5, } ] }); ``` {% endtab %} {% tab title="Recipes" %} ``` pushly('rate_item', { "recipes": [ { "id": "RECIPE_ID", "rating": 5, } ] }); ``` {% endtab %} {% endtabs %} ### Unrate Item Use this event when a user removes the rating from an item. {% tabs %} {% tab title="Products" %} ``` pushly('unrate_item', { "products": [ { "id": "PRODUCT_ID" } ] }); ``` {% endtab %} {% tab title="Events" %} ``` pushly('unrate_item', { "events": [ { "id": "EVENT_ID" } ] }); ``` {% endtab %} {% tab title="Recipes" %} ``` pushly('unrate_item', { "recipes": [ { "id": "RECIPE_ID" } ] }); ``` {% endtab %} {% endtabs %} ### Add To Cart Send this event whenever a user adds an item to their cart. Pushly will accumulate cart state across multiple calls. {% tabs %} {% tab title="Products" %} ``` pushly('add_to_cart', { "products": [ { "id": "PRODUCT_ID", "quantity": 1 } ] }); ``` {% endtab %} {% tab title="Events" %} ``` pushly('add_to_cart', { "events": [ { "id": "EVENT_ID", "quantity": 1 } ] }); ``` {% endtab %} {% endtabs %} You may call `add_to_cart` as many times as necessary to keep track of all items in a user's cart. Abandoned Cart notifications may be sent for any item in a customer's cart that has not been purchased. After a purchase is made the user's cart will be emptied and no notifications for a purchased item will be sent to the user. ### Update Cart Use this event when a user changes their cart without completing a purchase, such as adjusting quantities or removing items. To remove an item from the cart call the `update_cart` method with the full current cart information (omitting the removed item): {% tabs %} {% tab title="Products" %} ``` pushly('update_cart', { "products": [ { "id": "PRODUCT_ID", "quantity": 3 } ] }); ``` {% endtab %} {% tab title="Events" %} ``` pushly('update_cart', { "events": [ { "id": "EVENT_ID", "quantity": 3 } ] }); ``` {% endtab %} {% endtabs %} Or if the cart has been completely emptied provide an empty array: {% tabs %} {% tab title="Products" %} ``` pushly('update_cart', { "products": [] }); ``` {% endtab %} {% tab title="Events" %} ``` pushly('update_cart', { "events": [] }); ``` {% endtab %} {% endtabs %} ### Purchase Send this event after a successful checkout. This clears abandoned cart state and enables revenue attribution. {% tabs %} {% tab title="Products" %} ``` pushly('purchase', { "products": [ { "id": "PRODUCT_ID", "quantity": 1 } ], "price_value": "344.33", "purchase_id": "ABC123" }); ``` {% endtab %} {% tab title="Events" %} ``` pushly('purchase', { "events": [ { "id": "EVENT_ID", "quantity": 1 } ], "price_value": "344.33" "purchase_id": "ABC123" }); ``` {% endtab %} {% endtabs %} #### Purchase Fields * **price\_value** – Total purchase amount, in the currency configured for the domain * **purchase\_id** – Unique order identifier If a `purchase` event is sent without item data, Pushly will still clear the user’s cart state. #### Currency handling `price_value` must be provided in the currency configured for the domain in the platform’s domain settings. Use a period (`.`) as the decimal separator for all currencies, regardless of locale. **Do not use commas.** Examples: * USD: `"344.33"` * JPY: `"5000"` ### Required Fields Summary * `id` is required for all items * `quantity` is required only when tracking cart or purchase quantities * `rating` is required only when rating an item * Only one of `products`, `events`, or `recipes` should be included per call ### Implementation Best Practices Initialize the SDK early in the page lifecycle to avoid missed events. Use consistent item IDs across all interaction types so Pushly can correctly associate behavior. Trigger `purchase` events from a reliable confirmation step whenever possible to avoid false abandoned cart notifications. ## --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://documentation.pushly.com/integration/web-push/sdk/e-commerce-support.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.