> For the complete documentation index, see [llms.txt](https://developers.flipsnack.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.flipsnack.com/webhooks/cart-events.md).

# Cart events

Receive product and cart activity from an embedded catalog.

Sends product and cart activity from an embedded catalog to the host page. Each message includes an event envelope and cart items.

{% hint style="info" %}
This feature requires account enablement. Republish the catalog after it is enabled. Already-published catalogs do not emit events until republished.
{% endhint %}

The player posts one-way `postMessage` events. The host page decides how to use them. No SDK or additional script is required. The Share embed remains a bare `<iframe>`. Listen for `message` events on `window`.

You can also use the collection.getEmbed method to obtain the embed code. Then append `cartMode=native` or `cartMode=external` to the iframe `src`.

Two modes are available:

* `native` — The Flipsnack cart stays visible. Use it for analytics and CRM while Flipsnack owns checkout.
* `external` — The Flipsnack cart UI is hidden. Add does not write to the Flipsnack cart. Use it to drive the client's own cart and checkout.

The drop-in product-page modal is not part of this API. The catalog must be embedded in an iframe. Top-level catalogs do not post events.

Identify the iframe with `e.source`, not its origin. The player host is shared across white-label embeds. For multiple catalogs, route messages using `e.source` or `e.data.publication.hash`.

### Request parameters

| Name                  | Type   | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| --------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `hash` (required)     | string | The hash of the flipbook to embed. The player does not load without it.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `cartMode` (required) | string | Append this query parameter to the iframe `src`. The value must match exactly. `native` keeps the Flipsnack cart visible and emits `cart.item.added`, `cart.item.updated`, `cart.item.removed`, `cart.cleared`, and `cart.submitted`. `external` hides the header cart icon, badge, fly-in animation, cart panel, send-order, WhatsApp checkout, export list, and clear-list. The quantity stepper, product-detail popup, product tags, and Add control remain. Add posts `product.addToCartClicked` only and does not write to the Flipsnack cart. When omitted, the player posts `viewer.ready` only and drops later events. |

### Response parameters

With `cartMode` set and enabled access, the player sends a `postMessage` event. Each message is available as `e.data`. Additional fields may be added without changing `version`.

| Name          | Type   | Description                                                                                                                                                    |
| ------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `source`      | string | Discriminator for other `postMessage` traffic. Always `flipsnack`, including white-label embeds.                                                               |
| `version`     | number | Protocol version. The current value is `1`.                                                                                                                    |
| `type`        | string | Message direction. The current value is `event`. The host must not send player commands.                                                                       |
| `event`       | string | Event name. `viewer.ready.payload.events` lists events emitted during this session.                                                                            |
| `timestamp`   | number | Event posting time, using `Date.now()` milliseconds.                                                                                                           |
| `publication` | object | Identifies the flipbook that posted the event.                                                                                                                 |
| `payload`     | object | Event-specific parameters. Cart mutations always contain the full cart, never a delta. Media, stock, quantity-stepper, and personalization fields are omitted. |

#### Events

* `viewer.ready` — Posted once when the player mounts. Both modes emit it. It is not replayed.
* `product.clicked` — Posted in both modes when a shopper opens a product. Inline Add controls do not emit it.
* `product.addToCartClicked` — Posted in `external` mode when the shopper uses **Add**. It has no Flipsnack cart write, cart summary, or `lineId`. Bulk add emits one event per line.
* `cart.item.added` — Posted in `native` mode for a new cart line. Quantity additions emit `cart.item.updated`.
* `cart.item.updated` — Posted in `native` mode when an existing line quantity changes.
* `cart.item.removed` — Posted in `native` mode when one line is removed. It is not posted for bulk clears or successful email or Slack submits.
* `cart.cleared` — Posted in `native` mode when the shopper confirms **Clear list**. No item-removed events follow.
* `cart.submitted` — Posted in `native` mode on success only. It posts before email or Slack clears the local cart, or after WhatsApp sends. Failed submissions do not emit it.

#### Publication parameters

| Name   | Type   | Description                                                                |
| ------ | ------ | -------------------------------------------------------------------------- |
| `hash` | string | The flipbook hash. This differs from the collection hash in the embed URL. |

#### Cart parameters

| Name        | Type   | Description                 |
| ----------- | ------ | --------------------------- |
| `currency`  | string | Catalog currency.           |
| `itemCount` | number | Number of cart lines.       |
| `quantity`  | number | Sum of all line quantities. |
| `items`     | array  | Cart lines, in cart order.  |

#### Item parameters

| Name            | Type   | Description                                                                                                                                                                    |
| --------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `lineId`        | string | Cart-line identifier, using the catalog element ID.                                                                                                                            |
| `externalId`    | string | Product code from the catalog feed. `null` when missing or empty. Missing values log one warning per `lineId` per session. Product-tag clicks return `null` without a warning. |
| `variantId`     | string | Client SKU. `null` when missing or when it has the `fs-` prefix.                                                                                                               |
| `title`         | string | Product title.                                                                                                                                                                 |
| `quantity`      | number | Quantity for this line.                                                                                                                                                        |
| `price`         | string | Full product price.                                                                                                                                                            |
| `discountPrice` | string | Discounted price. Empty when there is no discount.                                                                                                                             |

#### Product parameters

| Name            | Type   | Description                                                                                                |
| --------------- | ------ | ---------------------------------------------------------------------------------------------------------- |
| `title`         | string | Product title.                                                                                             |
| `price`         | string | Full product price.                                                                                        |
| `discountPrice` | string | Discounted price. Empty when there is no discount.                                                         |
| `url`           | string | Catalog product URL. Empty when unavailable.                                                               |
| `externalId`    | string | Product code from the catalog feed. `null` when missing or empty.                                          |
| `variantId`     | string | Posted with `product.addToCartClicked` only. Client SKU, or `null` when missing or generated by Flipsnack. |

#### Event payload parameters

| Name               | Type   | Description                                                                                                                                                                       |
| ------------------ | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `cartMode`         | string | Posted with `viewer.ready`. The active mode is `native` or `external`. Omitted when absent from the iframe `src`.                                                                 |
| `events`           | array  | Posted with `viewer.ready`. Lists the events this session emits. `external` emits `viewer.ready`, `product.clicked`, and `product.addToCartClicked`.                              |
| `product`          | object | Posted with `product.clicked` and `product.addToCartClicked`. See product parameters.                                                                                             |
| `quantity`         | number | Posted with `product.addToCartClicked`. The shopper-selected quantity.                                                                                                            |
| `trigger`          | string | Posted with `product.clicked` and `cart.item.added`. Product-click values are `hotspot`, `cta`, or `detail`. The current cart-add value is `button`.                              |
| `item`             | object | Posted with `cart.item.added`, `cart.item.updated`, and `cart.item.removed`. See item parameters.                                                                                 |
| `previousQuantity` | number | Posted with `cart.item.updated`. The quantity before the change.                                                                                                                  |
| `cart`             | object | Posted with cart mutations. It contains the full cart after the change. It is empty after `cart.cleared`. Successful email and Slack submits clear it. WhatsApp leaves it intact. |
| `items`            | array  | Posted with `cart.cleared` and `cart.submitted`. Contains wiped or submitted lines.                                                                                               |
| `orderId`          | string | Posted with `cart.submitted`. Client-side identifier generated when the order modal opens. It is not a backend order number.                                                      |
| `deliveryMethod`   | string | Posted with `cart.submitted`. Values: `email`, `slack`, `email_and_slack`, or `whatsapp`.                                                                                         |
| `form`             | array  | Posted for email or Slack submissions. Contains configured contact-field names, not shopper values. Omitted for WhatsApp.                                                         |

### Error codes

This API does not return HTTP error codes. No cart events are posted when access is disabled, the catalog was not republished, or the catalog opens in a top-level tab. When `cartMode` is missing, the player posts `viewer.ready` only. Failed submissions do not post `cart.submitted`.

### Examples

#### Request

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

```html
<iframe id="catalog" src="https://player.flipsnack.com/?hash=d3m0h45h&cartMode=native"></iframe>
<script>
    const catalog = document.getElementById('catalog');

    window.addEventListener('message', (e) => {
        if (e.source !== catalog.contentWindow) return;
        if (e.data?.source !== 'flipsnack') return;

        if (e.data.event === 'cart.item.added') {
            console.log(e.data.payload);
        }
    });
</script>
```

{% endtab %}

{% tab title="external" %}

```html
<iframe id="catalog" src="https://player.flipsnack.com/?hash=d3m0h45h&cartMode=external"></iframe>
<script>
    const catalog = document.getElementById('catalog');

    window.addEventListener('message', (e) => {
        if (e.source !== catalog.contentWindow) return;
        if (e.data?.source !== 'flipsnack') return;

        if (e.data.event === 'product.addToCartClicked') {
            console.log(e.data.payload);
        }
    });
</script>
```

{% endtab %}
{% endtabs %}

#### Response

{% tabs %}
{% tab title="cart.item.added" %}

```json
{
  "source": "flipsnack",
  "version": 1,
  "type": "event",
  "event": "cart.item.added",
  "timestamp": 1742200001500,
  "publication": { "hash": "7c5e600d4459fe4e04d23ae5ei188777" },
  "payload": {
    "item": {
      "lineId": "el_4f2a",
      "externalId": "P001",
      "variantId": "P001-OAK",
      "title": "Scandinavian dining chair",
      "quantity": 1,
      "price": "327.99",
      "discountPrice": "232.99"
    },
    "cart": {
      "currency": "USD",
      "itemCount": 1,
      "quantity": 1,
      "items": [{
        "lineId": "el_4f2a",
        "externalId": "P001",
        "variantId": "P001-OAK",
        "title": "Scandinavian dining chair",
        "quantity": 1,
        "price": "327.99",
        "discountPrice": "232.99"
      }]
    },
    "trigger": "button"
  }
}
```

{% endtab %}

{% tab title="product.addToCartClicked" %}

```json
{
    "source": "flipsnack",
    "version": 1,
    "type": "event",
    "event": "product.addToCartClicked",
    "timestamp": 1742200001500,
    "publication": {
        "hash": "7c5e600d4459fe4e04d23ae5ei188777"
    },
    "payload": {
        "product": {
            "title": "Scandinavian dining chair",
            "price": "327.99",
            "discountPrice": "232.99",
            "url": "https://shop.example.com/products/P001",
            "externalId": "P001",
            "variantId": "P001-OAK"
        },
        "quantity": 1
    }
}
```

{% endtab %}
{% endtabs %}