# Commerce & Catalog Item Events

This guide explains how to send commerce and catalog-related user interactions to Pushly using the React Native SDK. These events power features like abandoned cart notifications, saved item reminders, revenue attribution, and catalog-driven recommendation campaigns.

The Pushly React Native 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 item requires an `id`. Quantity and rating are 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="React" %}

```typescript
PushSDK.UserProfile.viewItem({ id: 'ITEM_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="React" %}

```typescript
PushSDK.UserProfile.saveItem({ id: 'ITEM_ID' })
```

{% endtab %}
{% endtabs %}

### Unsave Item

Use this event when a user removes an item from the saved list, favorites, or bookmarks.

{% tabs %}
{% tab title="React" %}

```typescript
PushSDK.UserProfile.unsaveItem({ id: 'ITEM_ID' })
```

{% endtab %}
{% endtabs %}

### Complete Item

A user marks an item as completed after finishing its intended experience.

{% tabs %}
{% tab title="React" %}

```typescript
PushSDK.UserProfile.completeItem({ id: 'ITEM_ID' })
```

{% endtab %}
{% endtabs %}

### Uncomplete Item

Use this event to revert the completion of an item.

{% tabs %}
{% tab title="React" %}

```typescript
PushSDK.UserProfile.uncompleteItem({ id: 'ITEM_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.

{% tabs %}
{% tab title="React" %}

```typescript
PushSDK.UserProfile.rateItem({ id: 'ITEM_ID', rating: 5 })
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
The `rating` value should reflect your product's native scale — use whatever range makes sense for your use case (e.g., 1–5 for a star rating, 0–10 for a score, 1–100 for a percentage-style rating). The only requirement is that the value falls within 0–100 and has no more than 1 decimal place.
{% endhint %}

### Unrate Item

Use this event when a user removes the rating from an item.

{% tabs %}
{% tab title="React" %}

```typescript
PushSDK.UserProfile.unrateItem({ id: 'ITEM_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="React" %}

```typescript
PushSDK.UserProfile.addToCart([{ id: 'ITEM_ID', quantity: 5 }])
```

{% 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="React" %}

```typescript
PushSDK.UserProfile.updateCart([{ id: 'ITEM_ID', quantity: 7 }])
```

{% endtab %}
{% endtabs %}

Or if the cart has been completely emptied provide an empty array:

{% tabs %}
{% tab title="React" %}

```typescript
PushSDK.UserProfile.updateCart([])
```

{% endtab %}
{% endtabs %}

### Purchase

Send this event after a successful checkout. This clears abandoned cart state and enables revenue attribution.

{% tabs %}
{% tab title="React" %}

```typescript
PushSDK.UserProfile.trackPurchase(
    [{ id: 'ITEM_ID', quantity: 5 }], // items
    "ABC123",                         // purchase_id
    "344.33"                          // price_value
)
```

{% endtab %}
{% endtabs %}

#### Parameter order

`trackPurchase(items, purchase_id, price_value)`

Because this method uses positional parameters, values must be passed in this order:

* `items`
* `purchase_id`
* `price_value`

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

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