🚧
Work in progress
We're still writing this guide — details may change as it's finalized.
Reference Web Shopify WordPress

API Reference

Commands, events, and the drop-in instance — what the drop-in exposes and how to drive it from your storefront.

API Reference

Once you call dropInLoader.setConfig(...), you get back a drop-in instance that exposes the full programmatic surface. This page documents every method and event you can call on that instance.

The two surfaces that matter most are:

  • instance.commands.* — methods you call to tell the drop-in something (open the modal, set the user, set the cart, ...).
  • instance.On.* — methods you call to listen to what the drop-in is doing (user wants to log in, benefits changed, transaction code issued, ...).
import { dropInLoader } from "https://dropins.simplyclub.co.il/drop-ins/drop-in-loader/index.mjs";

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

// Commands — you call these
instance.commands.show();
instance.commands.setUser({ id: "u1", email: "dana@example.com" });

// Events — the drop-in calls these
instance.On.benefitSelectionsChanged((data) => { /* react */ });

Every On.* listener returns an unsubscribe handle: const sub = instance.On.X(cb); sub.off(); — call .off() when you're done.

Configuration

setConfig is the single entry point. Pass it once per page; subsequent calls return the same instance.

Option Type Required Default Description
poiId string Yes — Your Point-of-Interest ID from the SimplyClub dashboard.
env "prod" | "test" | "local" No "prod" API environment. Only switch to test when SimplyClub support tells you to.
starterBtn.selector string No — CSS selector for an element that opens the drop-in.
tagName string No simply-club-dropins Custom web-component tag name. Rarely needed.
user object No — Pre-populate the current user. Equivalent to calling setUser right after init. 
const instance = await dropInLoader.setConfig({
  poiId: "your-poi-id",
  env: "prod",
  starterBtn: { selector: "#membership-button" },
});

Commands

All commands live under instance.commands.*. They're synchronous unless noted otherwise.

commands.show(tabName?)

Opens the SimplyClub modal. Optionally pre-selects a tab inside the dashboard.

instance.commands.show();
instance.commands.show("benefits"); // open directly to the benefits tab

commands.hide()

Closes the modal.

instance.commands.hide();

commands.setUser(user | null)

Tells the drop-in who the current user is. Call this as soon as your site knows the user is logged in. Pass null to log them out of the drop-in's view (does not log them out of your site).

instance.commands.setUser({
  id: "user-123",
  firstName: "Dana",
  lastName: "Cohen",
  email: "dana@example.com",
  phone: "+972-50-1234567",
});

// On logout
instance.commands.setUser(null);

commands.setCart(cart | null)

Sends the current cart to the drop-in so benefits and points are calculated against the real basket. Pass null to clear.

Returns a Promise<true> once the cart is committed.

await instance.commands.setCart({
  token: "cart-token-123",
  items: [
    {
      id: "1",
      sku: "PROD-001",
      name: "Product Name",
      price: 49.90,      // major currency units (e.g. 49.90 NIS — NOT cents)
      final_price: 49.90,
      quantity: 1,
    },
  ],
  discount_codes: [],
});

The exact items[] shape depends on your platform. On Shopify the Theme App Block fills this in for you; on custom integrations, build whatever shape your loyalty program expects.

commands.getCart()

Returns the cart you last passed to setCart. Useful for debugging or re-checking state.

const cart = await instance.commands.getCart();

commands.logout()

Logs the user out of the SimplyClub session (clears the auth token in the drop-in). Does not log them out of your site.

await instance.commands.logout();

commands.getSession()

Returns the current SimplyClub session object. Mostly useful for debugging.

const session = await instance.commands.getSession();

commands.getTransactionCode()

Returns the current sc_transaction_code — the session-bound token your order webhook will need. Most stores capture this via the transactionCodeCreated event instead.

const code = await instance.commands.getTransactionCode();

commands.getBenefitSelections()

Returns what the user has currently selected in the drop-in (promos, quantities, totals).

const selections = await instance.commands.getBenefitSelections();

commands.resetBenefitSelections(callback?)

Clears all selected benefits — useful when the cart changes substantially (e.g. the user removed an item that was tied to a benefit).

instance.commands.resetBenefitSelections((data) => {
  console.log("selections reset", data);
});

commands.dispatchExampleTransaction()

Asks the drop-in to compute benefits for the current cart and dispatch the result without showing the modal. Useful for pages that want to display "you'd save X with the loyalty club" before the user opens the drop-in.

const result = await instance.commands.dispatchExampleTransaction();

Events

All listeners live under instance.On.*. Every listener returns { off: () => void } — call .off() to stop receiving the event.

On.redirectToLogin(callback)

Fires when the drop-in needs the user to be signed in to your site. Your job is to send them to your login flow.

const sub = instance.On.redirectToLogin(() => {
  localStorage.setItem("sc_post_login_redirect", window.location.href);
  window.location.href = "/login";
});

// Later, when the page unmounts:
sub.off();

On.transactionCodeCreated(callback)

Fires when the drop-in issues a new sc_transaction_code. This is the single most important event to wire up — without storing this code, your order webhook can't link the order back to SimplyClub.

instance.On.transactionCodeCreated((code) => {
  // Persist it on the cart so it carries into the order.
  // Shopify: write to cart attributes. WooCommerce: write to session/order meta.
  fetch("/api/cart/attach-simply-code", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ sc_transaction_code: code }),
  });
});

On.benefitSelectionsChanged(callback)

Fires whenever the user picks, changes, or clears a benefit. Persist the result so the discount carries through to checkout.

instance.On.benefitSelectionsChanged((data) => {
  // data contains: selectedPromos, serviceTranNumber, source, etc.
  fetch("/api/cart/apply-simply-discount", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(data),
  });
});

On.addItemToCart(callback)

Fires when the drop-in wants to add a product to your cart (e.g. a free gift, a benefit-bound product). Your callback is responsible for actually adding it.

instance.On.addItemToCart((item) => {
  // item.variant_id, item.quantity
  fetch("/cart/add.js", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ items: [{ id: item.variant_id, quantity: item.quantity }] }),
  });
});

On.membershipProductSelected(callback)

Fires when the user picks a paid membership product inside the drop-in. The event carries a resolve() you must call once you've added the product to your cart — the drop-in waits for it before continuing.

instance.On.membershipProductSelected(async (event) => {
  const product = event.product;
  await addToCart({ variant_id: product.id, quantity: 1 });
  event.resolve(); // tell the drop-in we're done
});

On.goToCheckout(callback)

Fires when the user clicks the drop-in's "go to checkout" action.

instance.On.goToCheckout(() => {
  window.location.href = "/checkout";
});

On.userLoggedIn(callback)

Fires when the SimplyClub session successfully resolves to a known member. Useful for showing member-only UI on your storefront.

instance.On.userLoggedIn((member) => {
  document.body.classList.add("is-simply-member");
});

Lower-level surfaces

These exist if you need fine-grained control. Most integrations don't need them — prefer commands and On.*.

instance.signal

Direct access to the internal event bus. The drop-in uses @simplyclub/signal underneath, and exposes it for advanced cases.

instance.signal.get("cart");
instance.signal.set("user", { id: "u1" });
instance.signal.on("cart", "my-listener", (cart) => { /* ... */ });
instance.signal.off("cart", "my-listener");

instance.debug

Drop-in-prefixed logging that respects the global debug flag (enabled via your POI's debugMode setting). Useful when you want your own logs to be filtered alongside SimplyClub's.

instance.debug.log("benefit applied", payload);
instance.debug.warn("retrying cart sync");
instance.debug.error("failed to add item", err);

Typical wiring (one block)

The most common integration is the same handful of commands and listeners. Here it is end to end, framework-free:

const instance = await dropInLoader.setConfig({
  poiId: "YOUR_POI_ID",
  starterBtn: { selector: "#membership-button" },
});

// 1. Tell the drop-in who's logged in
if (currentUser) {
  instance.commands.setUser({
    id: currentUser.id,
    firstName: currentUser.firstName,
    lastName: currentUser.lastName,
    email: currentUser.email,
  });
}

// 2. Sync the cart so benefits are calculated correctly
await instance.commands.setCart(getCurrentCart());

// 3. When the drop-in issues a transaction code, persist it onto the order
instance.On.transactionCodeCreated((code) => {
  attachToCart({ sc_transaction_code: code });
});

// 4. When the user picks a benefit, persist that too
instance.On.benefitSelectionsChanged((data) => {
  attachToCart({ sc_discount_info: JSON.stringify(data) });
});

// 5. Send users to your login when the drop-in asks
instance.On.redirectToLogin(() => {
  window.location.href = "/login";
});

Related