# Commerce & Catalog Item Events

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

The Pushly iOS 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.

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

```swift
PushSDK.UserProfile.viewItem(item: CatalogItem(id: "ITEM_ID"))
```

{% endtab %}

{% tab title="Objective-C" %}

```objective-c
CatalogItem *item = [[CatalogItem alloc] initWithId:@"ITEM_ID"];
[PushSDKUserProfile viewItemWithItem:item];
```

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

```swift
PushSDK.UserProfile.saveItem(item: CatalogItem(id: "ITEM_ID"))
```

{% endtab %}

{% tab title="Objective-C" %}

```objective-c
[PushSDKUserProfile saveItemWithItem:
    [[CatalogItem alloc] initWithId:@"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="Swift" %}

```swift
PushSDK.UserProfile.unsaveItem(
    item: CatalogItem(id: "ITEM_ID")
)
```

{% endtab %}

{% tab title="Objective-C" %}

```objective-c
[PushSDKUserProfile unsaveItemWithItem:
    [[CatalogItem alloc] initWithId:@"ITEM_ID"]
];
```

{% endtab %}
{% endtabs %}

### Complete Item

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

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

```swift
PushSDK.UserProfile.completeItem(
    item: CatalogItem(id: "ITEM_ID")
)
```

{% endtab %}

{% tab title="Objective-C" %}

```objective-c
[PushSDKUserProfile completeItemWithItem:
    [[CatalogItem alloc] initWithId:@"ITEM_ID"]
];
```

{% endtab %}
{% endtabs %}

### Uncomplete Item

Use this event to revert the completion of an item.

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

```swift
PushSDK.UserProfile.uncompleteItem(
    item: CatalogItem(id: "ITEM_ID")
)
```

{% endtab %}

{% tab title="Objective-C" %}

```objective-c
[PushSDKUserProfile uncompleteItemWithItem:
    [[CatalogItem alloc] initWithId:@"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**.

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

```swift
PushSDK.UserProfile.rateItem(
    item: CatalogItem(id: "ITEM_ID", rating: 95)
)
```

{% endtab %}

{% tab title="Objective-C" %}

```objective-c
CatalogItem *item = [[CatalogItem alloc] initWithId:@"ITEM_ID" rating:@95];
[PushSDKUserProfile rateItemWithItem:item];
```

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

```swift
PushSDK.UserProfile.unrateItem(
    item: CatalogItem(id: "ITEM_ID")
)
```

{% endtab %}

{% tab title="Objective-C" %}

```objective-c
[PushSDKUserProfile unrateItemWithItem:
    [[CatalogItem alloc] initWithId:@"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="Swift" %}

```swift
PushSDK.UserProfile.addToCart(
    item: CatalogItem(id: "ITEM_ID", quantity: 2)
)
```

{% endtab %}

{% tab title="Objective-C" %}

```objective-c
[PushSDKUserProfile addToCartWithItem:
    [[CatalogItem alloc] initWithId:@"ITEM_ID" quantity:2]
];
```

{% endtab %}
{% endtabs %}

You may call `add_to_cart` as many times as necessary to keep track of all items in a visitor'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 visitor's cart will be emptied and no notifications for a purchased item will be sent to the visitor. 

### 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="Swift" %}

```swift
PushSDK.UserProfile.updateCart(withItems: [
    CatalogItem(id: "ITEM_1", quantity: 1),
    CatalogItem(id: "ITEM_2", quantity: 2)
])
```

{% endtab %}

{% tab title="Objective-C" %}

```objective-c
NSArray *items = @[
    [[CatalogItem alloc] initWithId:@"ITEM_1" quantity:1],
    [[CatalogItem alloc] initWithId:@"ITEM_2" quantity:2]
];
[PushSDKUserProfile updateCartWithItems:items];
```

{% endtab %}
{% endtabs %}

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

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

```swift
PushSDK.UserProfile.updateCart(withItems: [])
```

{% endtab %}

{% tab title="Objective-C" %}

```objective-c
[PushSDKUserProfile updateCartWithItems:@[]];
```

{% endtab %}
{% endtabs %}

### Purchase

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

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

```swift
PushSDK.UserProfile.trackPurchase(
    of: [
        CatalogItem(id: "ITEM_1"),
        CatalogItem(id: "ITEM_2", quantity: 2)
    ],
    withPurchaseId: "ORDER_123",
    withPriceValue: "49.99"
)
```

{% endtab %}

{% tab title="Objective-C" %}

```objective-c
NSArray *items = @[
    [[CatalogItem alloc] initWithId:@"ITEM_1"],
    [[CatalogItem alloc] initWithId:@"ITEM_2" quantity:2]
];

[PushSDKUserProfile trackPurchaseWithItems:items
                      withPurchaseId:@"ORDER_123"
                     withPriceValue:@"49.99"];
```

{% endtab %}
{% endtabs %}

#### Purchase Fields

* **priceValue** – Total purchase amount, in the currency configured for the domain
* **purchaseId** – 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.