Cart Sync

Everything the drop-in calculates — which benefits apply, what discount to show, how many points the order would earn — runs against the cart you give it. If the cart in the drop-in doesn't match the cart in your store, the customer sees a benefit they can't redeem (or worse, redeems a benefit your checkout doesn't honor).

This guide explains the shape SimplyClub expects, when to push updates, and how to avoid the most common pitfall: an infinite cart-update loop.

How it works

1. On page load, push the current cart into the drop-in once.
2. Every time your storefront mutates the cart (add, remove, change quantity, apply a coupon, etc.), push the updated cart again.
3. When the user picks a benefit in the drop-in, persist the selection back onto your cart so the discount carries through to checkout. See API Reference → On.benefitSelectionsChanged.

import { dropInLoader } from "https://dropins.simplyclub.co.il/drop-ins/drop-in-loader/index.mjs";

const instance = await dropInLoader.setConfig({ poiId: "YOUR_POI_ID" });

// 1. Initial sync
await instance.commands.setCart(await readMyCart());

// 2. Re-sync on every cart change
onMyCartChange(async () => {
  await instance.commands.setCart(await readMyCart());
});

Cart shape

setCart takes one argument: the cart object. Pass null to clear.

type Cart = {
  token: string;            // any stable identifier — your cart hash, session id, etc.
  items: CartItem[];
  discount_codes?: string[]; // coupons the customer has already applied
};

Minimal item shape

type CartItem = {
  id: string | number;       // your platform's line-item or product id
  quantity: number;
  price: number;             // unit price in MAJOR currency units (e.g. 49.90)
  final_price: number;       // price after line discounts (also major units)
  title?: string;
  sku?: string;
};

That's all you need to make benefits calculate correctly. The richer the item, the more SimplyClub can do — see the full shape below.

Full item shape

Everything optional unless marked. Anything missing is treated as "not provided".

⚠️ Price units

This is the most common mistake. SimplyClub expects prices in major currency units — 49.90, not 4990.

• Shopify's /cart.js returns prices in minor units (cents/agorot). The SimplyClub Theme App Block divides them by 100 before calling setCart. If you build your own Shopify integration, do the same.
• WooCommerce's WC_Product::get_price() already returns major units — pass it through as-is.
• Custom backends: send whatever your storefront displays to the customer.

If your numbers look 100× off, this is why.

When to sync

Call setCart at every point your cart can change:

The rule of thumb: if the customer would see a different cart subtotal, re-sync.

Avoiding the infinite loop

The drop-in writes back to your cart when the user picks a benefit (typically by setting cart attributes or coupon codes). If your "cart changed" detector treats those writes as a real cart change, you'll end up in this loop:

benefit selected → drop-in writes to cart → your detector fires → you call setCart →
drop-in recalculates → fires benefit again → write to cart → … (forever)

The fix is to tag writes that originate from SimplyClub so your detector can ignore them.

Shopify

The Theme App Block already does this — every cart write the drop-in performs goes through ?simplyclub=true. The block's PerformanceObserver watches /cart/* calls and only resets the discount when another script mutates the cart:

const observer = new PerformanceObserver((list) => {
  list.getEntries().forEach((entry) => {
    if (entry.initiatorType !== 'fetch') return;
    if (!entry.name.includes('/cart/')) return;
    if (entry.name.includes('simplyclub=true')) return; // ignore our own writes
    if (entry.name.includes('/cart/add.js')) return;    // additive — keep the benefit
    handleCartChange(); // real external mutation — re-sync
  });
});
observer.observe({ type: 'resource' });

Custom integration

Apply the same idea to your stack:

async function updateCart(payload, opts = {}) {
  payload._sc = opts.fromSimplyClub === true; // tag origin
  const res = await fetch("/api/cart", { method: "POST", body: JSON.stringify(payload) });
  if (!opts.fromSimplyClub) {
    await instance.commands.setCart(await readMyCart()); // only re-sync on external writes
  }
  return res.json();
}

Two simple rules:

1. Mark every write you make on behalf of SimplyClub so your detector can skip it.
2. Re-sync only when the write is genuinely external — coming from the user's actions, another tab, or your own checkout code.

Recipes

Shopify

If you use the Theme App Block, cart sync is already wired — you don't need to do anything. If you're building your own Shopify integration, use the pattern the block uses:

async function syncShopifyCart() {
  const res = await fetch('/cart.js?_sc=1', { cache: 'no-store' });
  const cart = await res.json();

  const items = cart.items.map((i) => ({
    id: i.id,
    quantity: i.quantity,
    price: i.price / 100,                 // cents → major units
    final_price: i.final_price / 100,
    line_price: i.line_price / 100,
    final_line_price: i.final_line_price / 100,
    total_discount: i.total_discount / 100,
    discounts: (i.discounts || []).map((d) => ({ title: d.title, amount: d.amount / 100 })),
    title: i.product_title,
    sku: i.sku,
    vendor: i.vendor,
    image: i.image,
    url: i.url,
    variant_id: i.variant_id,
    variant_title: i.variant_title,
    variant_inventory_quantity: i.variant_inventory_quantity,
  }));

  await instance.commands.setCart({
    token: cart.token,
    items,
    discount_codes: cart.discount_codes || [],
  });
}

See Install on Shopify for the full block source.

WooCommerce

Render the cart from PHP on page load, then re-sync on AJAX cart events (WooCommerce fires wc_fragment_refresh and updated_cart_totals):

<script>
  window.simplyClub?.commands.setCart({
    token: "wc-<?php echo esc_js(WC()->session?->get_customer_id()); ?>",
    items: [
      <?php foreach (WC()->cart->get_cart() as $item):
        $product = $item['data']; ?>
      {
        id: "<?php echo esc_js($item['key']); ?>",
        quantity: <?php echo (int) $item['quantity']; ?>,
        price: <?php echo (float) $product->get_price(); ?>,
        final_price: <?php echo (float) $product->get_price(); ?>,
        title: "<?php echo esc_js($product->get_name()); ?>",
        sku: "<?php echo esc_js($product->get_sku()); ?>",
        image: "<?php echo esc_js(wp_get_attachment_url($product->get_image_id())); ?>",
        url: "<?php echo esc_js(get_permalink($product->get_id())); ?>"
      },
      <?php endforeach; ?>
    ]
  });

  jQuery(document.body).on('updated_cart_totals wc_fragments_refreshed', () => {
    fetch('/?wc-ajax=get_refreshed_fragments')
      .then((r) => r.json())
      .then(() => location.reload()); // simplest: reload to re-render PHP
  });
</script>

For SPAs or AJAX-heavy themes, expose a small REST endpoint that returns the cart as JSON and call it from JS instead of reloading.

Custom integration / SPA

Wire setCart to your state-management layer. Any time the cart slice changes, push it.

import { dropInLoader } from "https://dropins.simplyclub.co.il/drop-ins/drop-in-loader/index.mjs";
import { useEffect } from "react";
import { useCart } from "./store/cart";

const instance = await dropInLoader.setConfig({ poiId: "YOUR_POI_ID" });

function CartSync() {
  const cart = useCart();
  useEffect(() => {
    instance.commands.setCart({
      token: cart.token,
      items: cart.items.map((i) => ({
        id: i.id,
        quantity: i.qty,
        price: i.unitPrice,         // major units
        final_price: i.unitPrice - i.lineDiscount / i.qty,
        title: i.name,
        sku: i.sku,
        image: i.image,
      })),
      discount_codes: cart.couponCodes,
    });
  }, [cart]);
  return null;
}

Verifying the sync

1. Open your storefront and start the drop-in.
2. In DevTools: await window.simplyClub.commands.getCart() — confirm the returned cart matches what's in your storefront.
3. Add or remove an item. Re-run getCart() — the change should be reflected.
4. Open the drop-in modal. The displayed totals and applicable benefits should match the current cart.

If the drop-in shows stale data, your re-sync trigger isn't firing on that mutation type.

Common issues

Related

• API Reference — full commands and On.* surface.
• Install on Shopify — the Theme App Block handles cart sync automatically.
• Install on WordPress & Web — where to put the sync code.
• Order Webhook (Generic) — what happens to the cart after checkout.