Before you begin
Choose compatible Shopify product or variant metafield definitions and give the products or variants you want to preview a value. The definitions need storefront access. Keep units, punctuation, and meaning consistent across your products.
Metafield decorations change the content used by supported Order Editing cards, not the original product data in Shopify. Global settings apply across upsell strategies unless a strategy has its own override. Inventory and out-of-stock rules remain in Inventory settings.
Arrange your metafields
- Open Apps > Order Editing in Shopify admin.
- Open Upsell settings, then Metafield decorations.
- Select Add metafield decorations or Edit metafield decorations to open the dedicated editor.
- Choose a placement on the product-card diagram, such as Under the price. Its editing controls appear below the diagram.
- Select Add metafield and choose a compatible product or variant metafield.
- Set Text before, Text after, and Color if the value needs context. For example, place “Ships” before a shipping date. Keep this text short.
- Add another metafield to the same placement if you want to show two values together.
- Choose Side by side to show the second value next to the first, or New line to separate them.
- Use Move up, Move down, or Placement to reorder or move a mapping. You can also drag its chip onto another chip to pair them.
- Select Save in the page save bar when you are ready, or Discard to undo the page's unsaved changes.
The diagram remains available if a product preview cannot load. A placement stops offering additional metafields when it reaches its limit.
The placement description explains which surfaces support it and where content moves on compact cards. An existing Under the description mapping remains editable, even when a compact card shows that content under its price.
To remove mappings, select their checkboxes in Enabled metafields, then select Remove selected. Selecting rows does not disable their metafields. Removal is staged until you select Save; Discard restores the saved mappings.
Handle products without a value
For a variant metafield, select Add product fallback to use a product metafield when the variant's value is empty. A product metafield can similarly use Add variant fallback.
Choose the fallback from the picker and preview a variant without the primary value. If neither source has a displayable value, the label is omitted. To change the primary source, select Change metafield; selecting a replacement clears its previous fallback.
Replace default content
Use the image or title control in the diagram to replace that detail with a metafield. Add behavior in the page title bar offers other supported uses, including variant names, swatch colors, visibility, percentage discounts, and button text.
Choose the behavior, then select a compatible definition. A behavior generally has one mapping; image replacement can have both a product and a variant mapping. These choices are separate from ordinary labels, so you can keep adding labels even when all available behaviors are configured.
In the title or image dialog, select Done to stage your changes on the page, then Save in the page save bar. Cancel or closing the dialog discards that dialog's changes.
Use warning or critical colors only for information that needs a customer's attention. Image metafields must refer to supported Shopify media; the picker disables incompatible value types.
Preview the result
- Select Preview product in the page title bar and choose a product with known values.
- Use Variant in the title bar to inspect variants with different values or a configured fallback. This menu appears when the product has multiple variants.
- Use Surface in the title bar to compare Product list, Carousel, Featured product, Checkbox offer, and One-click upsell.
- Confirm the placement, pairing, text, and colors on each surface you use.
The same product and variant stay selected when you change surfaces. This preview checks appearance; it does not prove live targeting, payment, or an order modification. The strategy and branding settings can change the surrounding layout.
One-click upsell uses original metafield labels. It does not support image badges, custom pairing, or every color. Check this mode separately before relying on a decoration there.
If values do not appear
Check the exact product and variant's saved metafield values and the selected definition's storefront access. Review any mapping warning. If a definition was deleted or became inaccessible, choose a compatible replacement or remove that mapping, then save and preview again.
If no compatible definition appears, check its resource type and value type in Shopify. After creating or updating a definition, close and reopen the picker.
For a preview-service error, select Retry preview. A previous successful preview stays visible with a warning that it may be out of date. Your saved settings are unaffected by that preview error. If the settings themselves fail to load, use Retry before editing.
