Theme app blocks

Charm’s storefront surfaces are theme app blocks. You add them in the Shopify theme editor — no Liquid editing or code required.

Blocks

Block	Where it goes
Loyalty widget	App embed — floating launcher on every page
Product points	Product template — “earn X points”
Membership	Product template — presents paid plans
Redeem points	Cart page — the cart redemption box (the cart drawer needs no block)
Points badge	Any section — show live point values anywhere with Points Anywhere
Gate	Any template — members-only content when you require program opt-in
Landing: Hero (+ How it works, Ways to earn, Ways to redeem, VIP tiers, Referral, FAQ, Sign-up banner)	A Shopify page — the loyalty landing page sections

Adding a block

1. Online Store → Themes → Customize.
2. For the widget: App embeds → enable Charm loyalty widget.
3. For product blocks: open a product template → Add block → pick Charm product points / Charm membership.
4. Save. Charm auto-detects the live block and marks the surface Active under Visibility.

Once enabled, the widget renders as a floating launcher on every storefront page.

Styling

Colors, copy, and icon visibility are configured in the Charm admin — the blocks pick the settings up automatically, so you style once and every surface stays consistent. Changes appear on the storefront after the next page refresh.

Custom themes: when a section won’t accept app blocks

App blocks can only be dropped into sections that declare support for them. Most published themes do; hand-built themes sometimes don’t — the block simply never appears in that section’s Add block list.

The fix is two lines in the section’s schema and render loop, done once by whoever maintains the theme:

{%- case block.type -%}
  {% when '@app' %}
    {% render block %}
  {% comment %} ...the section's own block types... {% endcomment %}
{%- endcase -%}

"blocks": [
  { "type": "@app" }
]

After saving, every app block (Charm’s and any other app’s) becomes available in that section in the theme editor. For placements where even that isn’t possible — product cards in classic themes, quick-view modals — use the points-anywhere div instead.

Previewing blocks before the program is live

In the theme editor, every block you place renders your real staged configuration — your actual earn rules, rewards, VIP tiers, referral values and FAQ — even before the program is switched on. You style what shoppers will actually see, not grey placeholders.

One rule governs it: the editor previews the blocks you place; program switches don’t apply there. The points master switch, the referral rule, and the tiers switch decide what customers see. Inside the editor you control the preview by adding and removing blocks, so a points-off shop and a referrals-off shop behave identically. Placeholders appear only where something is genuinely unconfigured.

Two things that look like bugs but aren’t:

• On the live storefront, blocks render nothing while the program is off. That’s deliberate — no half-launched program leaks to shoppers, and it’s why the Visibility page tells you your landing blocks are placed but the program is off. The blocks come alive the moment the program is activated.
• The product points block shows an illustrative sample (a points figure roughly equal to the product price) rather than your earn rate. If the preview product costs 0 — a tour, a gift card — the sample bottoms out at “earn 1”. Pick a normally priced product in the editor’s preview picker to see a sensible sample.

Surface toggles are still respected in the editor: hiding the floating launcher or the header chip is a “where does UI appear” choice, not program state.

Which blocks need the app embed

The Charm Loyalty app embed is the shared runtime — it powers the floating widget and a few surfaces that plug into it. Several blocks carry their own script and work even with the embed off:

Surface	Needs the app embed?
Floating widget & panel	Yes — it is the embed
Header chip	Yes
Redeem points at the cart	Yes — the embed’s runtime powers the popup
Points-anywhere divs	Yes (the embed’s scanner fills them)
Charm product points (product page)	No — self-contained
Charm points on cards	No — ships its own scanner
Landing page blocks	No

Turning the floating launcher off in Charm → Visibility → Store widget does not disable the embed — the runtime keeps powering the chip, cart redemption, and points-anywhere placements. The separate Charm members-only gate embed (formerly “Charm Gate”) handles members-only content gating and renders nothing unless gating rules exist.