Kingsbell's commerce layer is built on Shopify-native product, variant, cart, search, collection, customer, and recommendation primitives. Alternate visual templates reuse this commerce engine rather than implementing separate purchasing logic.
Product presentation
The reusable product system supports:
- responsive product media;
- sale and sold-out states;
- currency and unit-price display;
- SKU and inventory information;
- pickup availability;
- product options and variant selection;
- high-variant products using option-value IDs;
- combined-listing-aware option URLs;
- quantity input;
- Ajax add to cart;
- dynamic checkout buttons;
- product-form errors and loading states;
- accordions and product information blocks;
- Shopify app blocks;
- complementary and related products.
Use the standard product template to validate data and behavior before applying an alternate product template.
Product options and variants
Kingsbell renders options from product.options_with_values and uses Shopify option-value identifiers where available. This is important for products with many variants and for combined listings.
When testing a product, include:
- a single-variant product;
- a product with multiple option groups;
- unavailable option combinations;
- sold-out variants;
- products with more than one media item;
- products with unit pricing;
- products with pickup availability;
- a combined-listing scenario when the store uses that feature.
Do not replace Shopify option URLs or variant identifiers with text-only matching.
Product forms
Product forms support Ajax submission and Shopify's normal purchase flow. A product section should always preserve:
- the selected variant ID;
- quantity;
- selling-plan data when applicable;
- validation errors;
- loading and disabled states;
- dynamic checkout configuration;
- app blocks placed by merchants.
When customizing the button or form layout, keep the native form contract intact.
Pricing
The shared price renderer handles:
- regular price;
- compare-at sale price;
- sold-out presentation;
- currency-code display when enabled;
- unit pricing.
Use the shared renderer on product cards, product pages, search results, and recommendations to prevent inconsistent price states.
Product cards
Reusable cards include:
- responsive primary media;
- optional secondary-image hover;
- badges;
- price rendering;
- availability state;
- quick add;
- merchant-configurable media ratio, alignment, hover style, and quick-add style.
Quick add must not bypass option selection for products that require a variant choice. Test single-variant and multi-variant products separately.
Collections
Collection templates support:
- collection imagery and description;
- native storefront filters;
- sorting;
- pagination;
- reusable product cards;
- Ajax updates;
- browser-history updates;
- empty states.
The collection banner is separated from the filter and product-grid section, allowing merchants to change the page introduction without replacing commerce logic.
Filtering and sorting
Kingsbell uses Shopify's native filter data. Ajax enhancement updates the collection or search result area while preserving URL state.
Validate:
- filter combinations;
- active-filter removal;
- price range inputs;
- sorting changes;
- pagination after filtering;
- browser back and forward navigation;
- copied filtered URLs;
- no-JavaScript behavior;
- empty result sets.
Do not invent filter values in theme code. Product taxonomy, options, availability, price, and metafield filters must come from Shopify's storefront filter configuration.
Cart drawer and cart page
Kingsbell includes a cart drawer and a full cart page. Ajax quantity and removal actions synchronize affected sections using Shopify bundled section rendering.
Test:
- adding from product forms and quick add;
- opening the drawer after add;
- changing quantity;
- removing an item;
- cart count updates;
- line-item properties;
- selling plans when used;
- unavailable inventory responses;
- empty cart;
- cart-page fallback when JavaScript is unavailable.
The theme must not calculate authoritative totals in JavaScript. Display the cart data returned by Shopify.
Search and predictive search
Predictive search can return:
- products;
- suggested queries;
- collections;
- pages;
- articles.
The search template supports native filters, sorting, pagination, and Ajax result updates.
Validate keyboard navigation, escaped search terms, no-result states, slow responses, and mobile behavior. Search results may expose published products even when a theme-facing member gate hides another template; secure private catalogs with Shopify publication and entitlement controls.
Recommendations
Related products are loaded through Shopify's Recommendations API. Recommendation sections should tolerate:
- no recommendations;
- fewer products than the configured limit;
- unavailable products;
- section reloads in the theme editor;
- delayed responses.
Recommendations are merchandising, not access control.
Navigation and customer entry points
Kingsbell supports multi-level desktop and mobile navigation, search, cart access, and Shopify's current customer-account component.
Header behavior includes:
- optional sticky positioning;
- brand logo or wordmark;
- desktop navigation;
- mobile navigation;
- search entry;
- cart entry;
- account or member-aware link.
Build menus in Shopify navigation and assign them through section settings. Avoid hard-coded storefront URLs; use Shopify route objects and link objects.
App compatibility
Product templates include app-block support. The Flexible content section can also render app blocks.
Before approving an app integration:
- place the app block in the theme editor;
- verify save and reload behavior;
- test mobile and desktop layouts;
- confirm scripts are not duplicated after section reload;
- review performance and privacy impact;
- confirm the app does not override cart, variant, or customer behavior unexpectedly.
Commerce regression checklist
After changing shared snippets, product sections, cards, cart JavaScript, filters, or search, retest:
- product options and availability;
- add to cart;
- cart drawer and cart page;
- pricing and currency display;
- collection filters and sorting;
- search and predictive search;
- recommendations;
- app blocks;
- customer-account routes;
- keyboard and reduced-motion behavior.
Alternate templates are considered valid only when these shared commerce flows continue to work.