Skip to main content

​
Liquid Cart And Checkout

Liquid themes own markup. The platform commerce runtime owns behavior. That keeps checkout rules in one tested place instead of duplicating them across every theme.

​
Product Form

Use productForm(...) with platform data: 
<form
  data-shoppex-product-form
  x-data="productForm({{ product | json_attr | raw }})"
>
  <button type="submit">Add to cart</button>
</form>
The runtime handles:
  • selected variant
  • addons
  • custom fields
  • quantity bounds
  • stock and out-of-stock states
  • add-to-cart payloads
  • buy-now payloads

​
Product Cards

Product cards can use platform Alpine controllers and data attributes: 
<article
  x-data="storefrontProductCard"
  data-product-id="{{ item.productId }}"
  data-variant-id="{{ item.variantId }}"
  data-unit-price="{{ item.unitPrice }}"
  data-is-out-of-stock="{% if item.isOutOfStock %}true{% else %}false{% endif %}"
>
  <h3>{{ item.title }}</h3>
  <button type="button" @click="incrementCart($event)">Add</button>
</article>
Do not calculate final price, stock, or listing order in Liquid. Render the producer-prepared fields.

​
Cart Drawer And Checkout Modal

Mount shared snippets from the layout: 
{% render "snippets/cart-drawer", ctx: ctx, shop: shop %}
{% render "snippets/checkout-modal", ctx: ctx, shop: shop %}
{{ storefrontCommerceScriptHtml | raw }}
The snippets provide markup. The platform script wires state, coupon validation, totals, and redirect.

​
Hosted Checkout

Checkout is always finalized by Shoppex hosted checkout. Liquid themes should not:
  • collect card data
  • create provider sessions directly
  • decide gateway state
  • infer payment status
The platform runtime creates the checkout handoff and redirects the buyer.

​
Safe Customization

Good customizations:
  • button labels
  • layout and spacing
  • icons and badges
  • drawer structure
  • empty-cart text
  • product-card presentation
Risky customizations:
  • replacing stock checks
  • bypassing quantity bounds
  • creating payment sessions from theme JavaScript
  • embedding a secret API key
  • manually constructing invoice URLs

​
Next Steps

Core Contract

Template vs producer responsibilities.

Troubleshooting

Fix add-to-cart, coupon, and checkout issues.