Configuring Your Store with UI Metadata
A complete reference for using UI Metadata to control how your Cart 2.0 storefront looks, behaves, and what it shows.
Last updated 7 days ago
Time — 20 minutes
Difficulty — Intermediate
What You'll Build: A working UI Metadata configuration that controls your storefront's layout, content, and behavior, using context and data settings to customize everything from product layouts and pricing display to store copy and feature toggles, without touching any code.
Prerequisites:
An active Upmind account.
Basic familiarity with Cart 2.0.
Access to Settings > Brand Settings in your Upmind admin panel.
A basic understanding of JSON formatting.
A read-through of Understanding the Cart Architecture to understand how configuration levels and inheritance work.
Cart 2.0 is designed to work out of the box, with no configuration required. If you do nothing, the cart uses recommended built-in defaults that work for most use cases.
What’s new in Cart 2.0 is the level of control you now have when you do want to customize things. Compared to the original cart, you can finely control:
Page templates.
How components render.
Visual behaviour across different pages.
Whether certain features are enabled or disabled.
An admin configurator panel is planned for 2026. Until then, all configuration is done by saving JSON settings into UI Metadata fields.
You can access the UI Metadata from Settings > Brand Settings under Branding and Customisation.
How configuration works
The Cart 2.0 uses two types of settings, each with a clear purpose.
1. Context settings
Control how things look and behave, such as layout and visibility.
Examples:
Layout and spacing.
Visibility of components.
Page behaviour.
Responsive behaviour by device size.
SEO settings.
2. Data settings
Control what content, values, and features are used and shown, such as headings, badges, and toggles.
Examples:
Text and labels.
Feature toggles.
Upsells and cross-sells.
Store copy and messaging.
All settings are optional. If a setting is not defined, the cart automatically falls back to a built-in default.
3. Configuration levels and how inheritance works in practice
1. Context settings (@context)
Use @context when you want to control layout, behaviour, or visual presentation of cart pages.
Key format
@context.<context>.<setting>[/<modifier>] = valueContext (<context>)
Defines where the setting applies:
catalogueconfigurerecommendationsbasketauthbilling_detailscheckoutconfirmation
Using * (global default) applies the setting everywhere unless overridden.
Setting (<setting>)
Defines what you are changing, for example:
productImagesproductListLayoutzeroPriceDisplay
Modifier (/<modifier>, optional)
Used for responsive behaviour:
sm– Mobilemd– Tabletlg– Desktop
If no modifier is used, the setting applies to all viewports.
To switch to Cart 2.0 and implement context settings, provide the following JSON in your UI Metadata:
Example{
"cart": {
"storefront_url": "https://{custom-domain}/order/shop"
}
}
Example 1: Show or hide product images
Global default: show product images everywhere.
JSON Example:
Example{
"@context.*.productImages": "visible"
}On the configure page: hide product images.
JSON Example:
Example{
"@context.configure.productImages": "hidden"
}Result:
Catalogue, basket, checkout, etc. > product images are visible
Configure page > product images are hidden
If this is set at the brand level, all products inherit it unless overridden at the category or product level.
Example 2: Display “0.00” prices as “Free”
Show "Free" instead of 0.00 across all contexts.
JSON Example:
Example{
"@context.*.zeroPriceDisplay": "label"
}"label"> displays Free"numeric"> displays 0.00
This applies globally, but can be overridden for specific categories or products.
Example 3: Change product list layout by viewport
Default: 4 columns on catalogue (all viewports).
JSON Example:
Example{
"@context.catalogue.productListLayout": "4-col"
}Default: 3 columns on catalogue (all viewports).
JSON Example:
Example{
"@context.catalogue.productListLayout": "3-col",
}Mobile (sm): switch to 1 column.
JSON Example:
Example{
"@context.catalogue.productListLayout/sm": "1-col",
}Tablet (md): use 2 columns.
JSON Example:
Example{
"@context.catalogue.productListLayout/md": "2-col"
}Behaviour:
Desktop > 3 columns
Tablet > 2 columns
Mobile > 1 column
This allows responsive layouts without custom code.
SEO Settings
SEO settings in Upmind let you define meta information at three scope levels (Brand, Product Category, and Product) across any context. You can customise page titles, descriptions, and other metadata to match different parts of your storefront.
Users can also override SEO metadata at any level, so a specific product or category can have its own meta details that take priority over broader brand-level defaults.
JSON Example: Overriding the SEO page title across your brand.
Example{
"@context.*.seoTitle": "Build YOur Website | Top Hosting Services"
"@context.configure.seoDescription": "Build YOur Website | Top Hosting Services"
}Appendix: SEO Settings
Appendix: UI Properties
Locked - This means that some properties have forced values in certain contexts.
2. Data settings (@data)
Use @data when you want to control content, relationships, or feature toggles.
Data settings define what the cart shows or enables, rather than how it looks. They can also vary by context and viewport modifier, so the same data property can have different values on mobile, tablet, or desktop.
Key format:
@data.<setting>[/<modifier>] = valueFor example:
@data.storeHeadingapplies the default value.@data.storeHeading/mdapplies the value on tablet.@data.storeHeading/lgapplies the value on desktop.
🚧 Data settings do not use context wildcards.
This makes it possible to customise store copy and other data-driven content to different screens while keeping the configuration centralized.
To switch to Cart 2.0 and implement data settings, provide the following JSON in your UI Metadata:
Example{
"cart": {
"@data.storeUrl": "https://{custom-domain}/order/shop"
}
}
Example 1: Set basic store copy
JSON Example:
Example{
"@data.storeHeading": "Welcome to Example Hosting",
"@data.storeSubHeading": "Choose the right plan for your website.",
}This controls user-facing text displayed in the cart.
Example 2: Disable the catalogue
JSON Example:
Example{"@data.catalogueDisabled":true}When enabled, the catalogue is hidden, and users can only access individual product pages directly.
Example 3: Upsell a product option within the basket
Full Domain Protection. JSON Example:
Example{
"@data.optionUpsellEnabled": true,
"@data.optionBadge": "Recommended",
"@data.optionBenefits": [
{ "label": "Prevents hackers from stealing...", "icon": "check" },
{ "label": "Requires your approval via...", "icon": "check" },
],
}This enables an in-basket upsell for a product option, including badges and benefit messaging.
Appendix: Data Properties
3. Configuration levels and how inheritance works in practice
You can define settings at different scopes. The cascade order (most specific > least specific):
Option — Settings on a specific sub-product option
Option Category — Settings on an option group
Product — Settings on a specific product
Product Category — Settings on a group of products
Brand — Your overall brand/storefront-level default
System Default — The built-in default value if nothing else is set
For every product, Cart 2.0 resolves settings using a fallback chain:
product → category → brand → internal default This means:
The most specific setting always wins.
You only override what you need.
Everything else is inherited automatically.
If you define just one key at the product level, all other settings will still come from the category or brand.
At each level, it looks for:
@context.<contextId>.<setting>If not found,
@context.*.<setting>If still not found, the built-in default is used
Because missing values are filled in automatically:
You never need to duplicate full configurations.
You can safely override only what matters.
Defaults remain consistent across the cart.
This keeps configuration clean, predictable, and scalable, even across large product catalogs.
Complete example
The following JSON configuration brings together a range of context and data settings into a single working UI Metadata block. It covers layout, content, visibility, and behavior across multiple pages, and demonstrates how global defaults and page-specific overrides work together.
JSON Example
Example{
"cart": {
"storefront_url": "https://store.yourdomain.com/order/shop"
},
"@context.*.theme": "yourbrand",
"@context.*.zeroPriceDisplay": "label",
"@context.*.breadcrumbs": "hidden",
"@context.*.productImages": "visible",
"@context.*.trustMessaging": "visible",
"@context.*.template": "two-column-ltr",
"@context.auth.template": "canvas-card",
"@context.configure.template": "two-column-rtl",
"@context.basket.template": "two-column-ltr",
"@context.checkout.template": "two-column-ltr",
"@context.confirmation.template": "full",
"@context.catalogue.productListLayout": "3-col",
"@context.catalogue.productListLayout/sm": "1-col",
"@context.catalogue.productListLayout/md": "2-col",
"@context.catalogue.productStyle": "carded",
"@context.catalogue.productImages": "visible",
"@context.catalogue.productBenefits": "visible",
"@context.catalogue.productAnchorPrice": "visible",
"@context.catalogue.productBadge": "visible",
"@context.catalogue.categoryImages": "visible",
"@context.catalogue.categoryListLayout": "3-col",
"@context.configure.productImages": "hidden",
"@context.configure.optionSelector": "radio-grid",
"@context.configure.optionSelectorGrid": "2-col",
"@context.configure.optionSelectorIcons": "visible",
"@context.configure.termSelector": "radio-grid",
"@context.configure.termSelectorGrid": "2-col",
"@context.configure.termSelectorSummary": "visible",
"@context.configure.productConfigSummary": "visible",
"@context.configure.productConfigOptionsSummary": "visible",
"@context.basket.basketSummary": "visible",
"@context.basket.basketTaxes": "consolidated",
"@context.basket.trustMessaging": "visible",
"@context.checkout.basketItems": "visible",
"@context.checkout.basketSummary": "visible",
"@context.checkout.paymentGatewaysCap": "3",
"@context.checkout.trustMessaging": "visible",
"@context.checkout.billingDetails": "editable",
"@context.recommendations.productStyle": "carded",
"@context.recommendations.productImages": "visible",
"@context.recommendations.productNativeRecommendations": "visible",
"@data.storeHeading": "Find the Right Plan for You",
"@data.storeSubHeading": "Simple pricing, no hidden fees.",
"@data.storeBadge": "New Plans Available",
"@data.storeUrl": "https://store.yourdomain.com",
"@data.displayFontLink": "https://fonts.googleapis.com/css2?family=Inter:wght@400;600;700&display=swap",
"@data.trustMessagingMarkdown": "🔒 Secure checkout · 30-day money-back guarantee · 24/7 support",
"@data.clickwrapDisclaimer": "By completing your purchase, you agree to our [Terms of Service](https://yourdomain.com/terms) and [Privacy Policy](https://yourdomain.com/privacy).",
"@data.trimTrailingZeroes": true
}Error handling and invalid values
Cart 2.0 does not throw hard errors when an invalid value is used in UI Metadata. Instead, it silently falls back to the built-in default for that setting and ignores the unrecognized value. This means a typo or unsupported value will not break your storefront, but the setting will have no visible effect, which can be difficult to spot.
JSON Example:
Example{
"@context.catalogue.productListLayout": "5-col"
}5-col is not a valid value for productListLayout. Therefore, Cart 2.0 will ignore it and fall back to the default 3-col layout. No error will appear in the UI.
Common mistakes to watch for:
Misspelled property names (e.g.
produtImagesinstead ofproductImages): The setting is silently skipped.Using a value outside the accepted enum (e.g.
"visible"on a property that only accepts column values).Missing or extra commas in your JSON: This will cause the entire UI Metadata block to fail to parse, reverting all settings to defaults
Applying a context that does not support the setting (e.g. using
@context.confirmation.optionSelector): The setting is ignored.
The safest way to confirm a setting is working is to check the storefront visually after saving, and cross-reference the property's accepted values in the UI Properties appendix and Data Properties appendix.