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.

This feature requires account enablement. Republish the catalog after it is enabled. Already-published catalogs do not emit events until republished.

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

native

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

external

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

Response

cart.item.added

{
  "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"
  }
}

product.addToCartClicked

{
    "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
    }
}