# 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.

##