# Developer reference

> The storefront events Kera fires, the cart actions it supports, the window.Kera functions custom code can call, and how the theme is built.

Source: https://spellnsell.com/themes/kera/docs/reference/developer-events · Kera 1.0.0 · Updated 2026-11-14

For developers adding custom code or apps. Kera follows Shopify's [standard storefront events and actions](https://shopify.dev/docs/api/storefront-events-and-actions), so code written for that standard works unchanged. Events are bubbling DOM events named `shopify:*`, heard on `document`. Actions live on `window.Shopify.actions`.

:::warning
Code changes aren't covered by theme support or carried into new versions. Duplicate the theme first. See [Update the theme](https://spellnsell.com/themes/kera/docs/help/updating).
:::

## Events

| Event | When | Dispatched on |
| --- | --- | --- |
| `shopify:page:view` | Every page load. | `document` |
| `shopify:product:view` | A product page, quick view, Featured product section or product card is viewed. See the contexts below. | A hidden element inside the product or card |
| `shopify:product:select` | An option changes on the product page, Featured product section or quick view. Resolves with the variant, or `null` when the combination doesn't exist. | The product's `<product-info>` element |
| `shopify:collection:view` | Collection page load. | A hidden element in the collection section |
| `shopify:collection:update` | Filters or sort change. Resolves with `productsCount`. | The filter form |
| `shopify:search:update` | Search page load with a query, and filter or sort changes. Resolves with `totalCount`. | The search section or the filter form |
| `shopify:cart:view` | Cart page load (`context: 'page'`) and each cart drawer open (`'dialog'`). | A hidden element in the cart section or drawer |
| `shopify:cart:lines-update` | Any add, quantity change or removal through the theme. `action`: `add`, `update` or `remove`. `context`: `cart` in the bag (including suggestions and the free gift), `dialog` in quick view, `product` elsewhere. | The cart drawer, or the cart page section |
| `shopify:cart:note-update` | The order note is saved. | Same as above |
| `shopify:cart:discount-update` | A discount code is applied or removed. A code that doesn't apply resolves with `userErrors`. | Same as above |
| `shopify:cart:error` | A cart request failed. | Same as above |

`shopify:product:view` contexts:

| Where | `context` | When |
| --- | --- | --- |
| Product page | `page` | Page load |
| Quick view | `dialog` | Each open |
| Featured product section | `page` | Once, when half on screen |
| Product card on the search page | `search` | Once, when half on screen |
| Product card on product and cart pages | `recommendation` | Once, when half on screen |
| Any other product card | `collection` | Once, when half on screen |

## Actions

| Action | What the theme does |
| --- | --- |
| `updateCart` | Shopify's default update, then redraws the bag and the header count. |
| `openCart` | Opens the cart drawer, or goes to the cart page when **Cart type** is **Page**. Does nothing on the cart page. |

## Functions on window.Kera

| Function | What it does |
| --- | --- |
| `Kera.refreshCart()` | Redraws the bag and header count from the current cart. Returns a promise. |
| `Kera.openCart()` | Same as the `openCart` action. |
| `Kera.openDrawer()` / `Kera.closeDrawer()` | Opens or closes the cart drawer when it is on the page. |
| `Kera.addToCart(body)` | Adds items in Ajax API format (`{ items: [{ id, quantity, properties }] }`), redraws the bag, fires `shopify:cart:lines-update` and follows **After adding to the bag** (**Theme settings > Cart**). Rejects with the cart's error message. |
| `Kera.openQuickView(url, trigger)` / `Kera.closeQuickView()` | Opens quick view for a product URL, returning focus to `trigger` on close; or closes it. Without the **Quick view** section in Overlays, opening goes to the product page. |
| `Kera.subscribe(topic, handler)` | Calls `handler(payload)` for each theme message on `topic` (see below). Returns a function that unsubscribes. |
| `Kera.formatMoney(cents)` | Formats an amount in cents with the store's money format, for example `formatMoney(15000)`. |
| `Kera.fetchSections(ids, url)` | Renders the section IDs (an array) for `url` (default: the current page) with the Section Rendering API. Resolves with `{ id: html }`. |
| `Kera.routes`, `Kera.strings`, `Kera.template`, `Kera.moneyFormat`, `Kera.cartType` | Read-only values: Shopify routes, a few translated strings, the template name, the store's money format and **Cart type**. |

Topics for `Kera.subscribe`:

| Topic | When | Payload |
| --- | --- | --- |
| `cart:update` | The bag changed through the theme. | The Ajax API cart object |
| `cart:error` | An add failed. | The Ajax API error (`status`, `message`, `description`) |
| `drawer:open` | The cart drawer or quick view opens. | `'cart'` or `'quick-view'` |
| `drawer:close` | The cart drawer closes. | `'cart'` |
| `variant:change` | A product form's variant changes. | `{ variant, sectionId }` |
| `variant:media` | A variant change moves the gallery to its photo. | `{ mediaId, sectionId }` |

## Good to know

:::details How do I listen to an event?
Event data is on the event object. Most events carry a `promise` that settles once the change is complete; wait for it before reading the result.

```js
document.addEventListener('shopify:cart:lines-update', async (event) => {
  const { action, context, lines } = event;
  const { cart, userErrors } = await event.promise;
  if (userErrors?.length) return; // Shopify declined the change, for example sold out
  console.log(`${action} from ${context}: the bag now holds ${cart.totalQuantity}`);
});
```

A change the cart declines (sold out, over a quantity limit) resolves with `userErrors` and `cart: null`. A request that fails (network down, server error) fires `shopify:cart:error` with `code: 'SERVICE_UNAVAILABLE'`, and the promise rejects.
:::

:::details How do I update the cart with an action?
```js
const { cart, userErrors } = await Shopify.actions.updateCart({
  lines: [{ merchandiseId: 'gid://shopify/ProductVariant/123456789', quantity: 1 }],
});
if (!userErrors?.length) Shopify.actions.openCart();
```
:::

:::details My code uses the Ajax cart API. How do I redraw the bag?
Call `Kera.refreshCart()` after `/cart/add.js` or `/cart/change.js`. The functions exist once the theme's scripts load, so check first, for example `window.Kera?.refreshCart?.()`.

```js
await fetch('/cart/add.js', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ items: [{ id: 123456789, quantity: 1 }] }),
});
await window.Kera.refreshCart();
window.Kera.openCart();
```
:::

:::details Where does the event data come from?
View events use Liquid's `standard_event_data` filter. Cart events are built from the Ajax cart response. Shopify's event library loads from `cdn.shopify.com/storefront/standard-events.js`; if it can't load, the theme works but fires none of these events.

The product form also fires `cart:added` on the `<form>` after a successful add, with no data, for older custom code. Use `shopify:cart:lines-update` instead. The theme listens to the editor's `shopify:section:*` and `shopify:block:*` events but doesn't fire them.
:::

:::details How is the theme built?
- **Blocks are private.** All files in `blocks/` start with `_`, so each block belongs to its section. Only these sections accept `@theme` blocks: `main-product`, `featured-product`, `main-article`, `image-with-text` and `rich-text`. `@app` blocks: `main-product`, `featured-product`, `main-cart`, `cart-drawer` and `apps`.
- **CSS variables** are set on `:root` in `snippets/css-variables.liquid`: colors (`--color-background`, `--color-text`, `--color-accent`, `--color-button`, `--color-border`), type (`--font-heading`, `--font-body`, `--size-h1` … `--size-body`), spacing (`--space-1` … `--space-9`, `--section-space`, `--page-margin`, `--page-max-width`) and `--radius`.
- **Color schemes** are classes: `.color-scheme-1` and so on, from each scheme's ID. `.color-mobile-<id>` and `.color-desktop-<id>` apply a scheme on phones or from 750px only.

| File | What it holds |
| --- | --- |
| `assets/standard-events.js` | Page view, view events and the search page load event. |
| `assets/cart.js` | Cart events and the `window.Kera` cart functions. |
| `assets/product.js` | Option changes (`shopify:product:select`). |
| `assets/facets.js` | Filter and sort changes. |
| `assets/product-card.js` | Card and Featured product views. |
| `layout/theme.liquid` | The `updateCart` and `openCart` action setup, before `content_for_header`. |
| `snippets/import-map.liquid` | Maps Shopify's event library. |
:::
