Shortcodes & Tags

Join Markt is not Shopify Liquid. Developers use four surfaces:

Nunjucks tags — {% markt_component %}, {% markt_snippet %}
Nunjucks context + filters — products, store, shopUrl, formatPrice, …
Helpers — helpers.components.products.getItemsByIds(items, ids)
HTML embed attributes — data-markt-* buy buttons on external sites
Vite / React — TypeScript + storefront API (no template tags)

API version: MARKT_NUNJUCKS_API_VERSION 1.0.0 — see Nunjucks Theme API.

Display products (Nunjucks)

Homepage / products grid (groups-aware)

Prefer catalogItems so group cards appear once and grouped products are not duplicated:

<section class="product-grid">
  {% for item in catalogItems %}
    {% if item.kind == 'group' %}
      <article class="product-card">
        <a href="{{ ('/group/' ~ item.group.id) | shopUrl }}">
          <h3>{{ item.group.name }}</h3>
          <p>From {{ item.group.minPrice | formatPrice(currency) }}</p>
        </a>
      </article>
    {% else %}
      {% set product = item.product %}
      <article class="product-card">
        <a href="{{ ('/product/' ~ product.slug) | shopUrl }}">
          {% if product.image %}
            <img src="{{ product.image | imageUrl }}" alt="{{ product.name }}" />
          {% endif %}
          <h3>{{ product.name }}</h3>
          {% if product.visibility == 'on-hold' %}<p>On hold</p>{% endif %}
          <p>{{ product.minPrice | formatPrice(currency) }}</p>
        </a>
      </article>
    {% endif %}
  {% else %}
    <p>No products yet.</p>
  {% endfor %}
</section>

Context comes from buildMarktStorefrontContext(). Use standaloneProducts for ungrouped-only lists; use full products for detail pages and group members.

Featured by id or slug

{% set ids = ['starter-plan', 'pro-plan'] %}
{% set featured = helpers.components.products.getItemsByIds(products, ids) %}

{% for product in featured %}
  <a href="{{ ('/product/' ~ product.slug) | shopUrl }}">
    {{ product.name }} — {{ product.minPrice | formatPrice(currency) }}
  </a>
{% endfor %}

Limit for homepage

{% for product in products.slice(0, 8) %}
  {# first 8 #}
{% endfor %}

Current product page

On templates/product.njk, use product (or null if missing).

Platform tags

Tag	Example
`markt_component`	`{% markt_component "navbar" %}`
`markt_snippet`	`{% markt_snippet "meta-tags.njk" %}`

Legacy imported themes may use {% render_component %} / {% render_snippet %} via the optional markt.sellauth extension — native themes should use markt_* only.

Core filters

Filter	Example
`assetUrl`	`{{ "pro.css" \| assetUrl }}`
`shopUrl`	`{{ "/products" \| shopUrl }}`
`apiUrl`	`{{ "v1/cart" \| apiUrl }}` → `/api/v1/cart`
`imageUrl`	Absolute URL for relative images
`formatPrice`	`{{ product.price \| formatPrice(currency) }}`
`formatDate` / `formatDateTime`	Locale dates
`json`	Safe JSON for `<script>`
`themeColor`	Accent from `settings.json`

Cart (theme + platform)

Cart source of truth: browser localStorage key cart (appCart).

Add: appCart.add(productId, variantId, quantity) — skip when product.visibility == 'on-hold'
Resolve lines: GET /api/v1/cart?storeId=&shopId=&cart=
Checkout: theme checkout() using appCart.items → POST /api/v1/checkout → /checkout/{orderId}

Use camelCase fields (product.image, product.slug, variant.quantityMin). There is no {% markt_cart %} tag — cart is JS + API.

Embed buy shortcodes (external HTML)

For merchant sites outside the theme (Webflow, custom HTML). Load the embed script, then use product CUID attributes — not Liquid tags.

<script src="https://YOUR_APP_ORIGIN/embed/embed.iife.js" defer></script>
<script>
  document.addEventListener('DOMContentLoaded', () => {
    Markt.init()
  })
</script>

<button
  data-markt-product-id="PRODUCT_CUID"
  data-markt-variant-id="VARIANT_UUID"
  data-markt-quantity="1"
  data-markt-theme="auto"
>
  Buy Now
</button>

Attribute	Required	Notes
`data-markt-product-id`	Yes	Product CUID
`data-markt-variant-id`	If variants	Stable UUID
`data-markt-quantity`	No	Default `1`
`data-markt-theme`	No	`auto` \| `light` \| `dark`
`data-markt-return-url`	No	After paid
`data-markt-email`	No	Prefill
`data-markt-coupon-code`	No	Coupon
`data-markt-metadata`	No	JSON string map

JS API: Markt.init(), Markt.open({ items, theme }), Markt.close(). Dashboard → product → Embed Checkout generates snippets. Demo: /embed/demo.html.

Vite / React (no `{% %}` shortcodes)

import { buildCatalogItems } from '@/lib/product-groups'
import { isStoreProductOnHold } from '@/lib/storefront-api'

const { products, groups } = useStore()
const items = buildCatalogItems(products, groups).slice(0, 8)

return (
  <section>
    {items.map((item) =>
      item.type === 'group' ? (
        <GroupCard key={item.group.id} group={item.group} />
      ) : (
        <ProductCard
          key={item.product.id}
          product={item.product}
          onHold={isStoreProductOnHold(item.product)}
        />
      ),
    )}
  </section>
)

Visual Builder sections map to React components; sellers edit content in the dashboard.

Anti-patterns

Inventing Shopify-style {% product_grid %} Liquid tags
Looping raw products for the homepage when groups exist (duplicates)
Allowing Add to cart on visibility === 'on-hold'
Putting | json inside x-data="..." or HTML attributes without encoding
Dumping full product descriptions into <head> scripts
Redefining Alpine.data('cartPage')
Hardcoding prices that ignore the catalog API
Custom card payment forms inside the theme
Calling /api/dashboard/* from the public storefront
Using SellAuth snake_case field names in native themes

See Nunjucks Theme Pitfalls.

​Shortcodes & Tags

​Display products (Nunjucks)

​Homepage / products grid (groups-aware)

​Featured by id or slug

​Limit for homepage

​Current product page

​Platform tags

​Core filters

​Cart (theme + platform)

​Embed buy shortcodes (external HTML)

​Vite / React (no {% %} shortcodes)

​Anti-patterns