Product and variant mapping for Loomi for Shopify
Loomi for Shopify syncs your Shopify product catalog to Bloomreach item collections. The catalog includes products and variants: a product is the parent item, while a variant is a purchasable combination such as a color, size, price, availability, or inventory level. The resulting item data can support Bloomreach use cases such as search, recommendations, collections, merchandising, and personalization,
This article explains how Shopify product and variant fields map to item collection attributes. It separates Bloomreach system attributes, which use reserved names and support common catalog capabilities, from integration-specific attributes stored in the main attribute family.
NoteProduct and variant metafields configured in the Loomi for Shopify integration are included in
purchase_itemevents. They aren't included in web events such asview_item,add_to_cart, orview_quickview.
How the mappings are organized
The mappings are grouped by record type and destination attribute family:
- Product mappings apply to the parent product record and describe the product across its variants
- Variant mappings apply to an individual purchasable variant
- System attributes are standard item collection attributes such as
active,brand,category_paths,price,stock_level,title, andurl. They support common catalog functionality such as display, availability, search, and recommendations mainattributes preserve additional Shopify product and variant data in source-shaped or integration-specific fields. Somemainattributes intentionally duplicate a system attribute, such astitle,description, orprice
The system and main labels refer to the destination attribute family in the item collection. They do not necessarily represent Shopify API namespaces. Source paths can include nested objects, arrays, and custom expressions
Product mappings
Product: system attributes
| Shopify source field | Item collection attribute | Description |
|---|---|---|
| collections (custom expression: title + numeric ID) | category_paths | Product collections transformed into category paths using each collection's title and numeric ID |
| default.featuredImage.url | large_image | URL of the product's default featured image |
| default.featuredImage.url | thumb_image | URL of the product's default featured image |
| default.totalInventory | stock_level | Total inventory across the product's variants |
| description | description | Product description text |
| isPublished | active | Whether the product is published on the online store |
| onlineStoreUrl | url | Canonical online store URL for the product |
| options[].name | variant_options | Names of the options that define the product's variants |
| publishedAt | launch_date | Date and time when the product was published |
| title | title | Product title |
| vendor | brand | Vendor or brand that supplies the product |
| vendor | supplier | Vendor or brand that supplies the product |
Product: main attributes
main attributes| Shopify source field | Item collection attribute | Description |
|---|---|---|
| contextualPricing.compareAtPriceRange.maxVariantCompareAtPrice.amount | maxVariantCompareAtPrice | Highest compare-at price among the product's variants for the configured market |
| contextualPricing.compareAtPriceRange.minVariantCompareAtPrice.amount | minVariantCompareAtPrice | Lowest compare-at price among the product's variants for the configured market |
| contextualPricing.priceRange.maxVariantPrice.amount | maxVariantPrice | Highest contextual price among the product's variants for the configured market |
| contextualPricing.priceRange.minVariantPrice.amount | minVariantPrice | Lowest contextual price among the product's variants for the configured market |
| default.createdAt | createdAt | Date and time when Shopify created the product |
| default.descriptionHtml | descriptionHtml | Product description in HTML format |
| default.featuredImage | featuredImage | Default featured image object |
| default.featuredImage.url | featuredImage.url | URL of the product's default featured image |
| default.handle | default.handle | URL-friendly product handle |
| default.hasOnlyDefaultVariant | hasOnlyDefaultVariant | Whether the product has only its default variant |
| default.images[].url | images | URLs of the product's images |
| default.isGiftCard | isGiftCard | Whether the product is a gift card |
| default.options | options | Product options that define the available variants |
| default.seo.description | seo.description | SEO description for the product |
| default.seo.title | seo.title | SEO title for the product |
| default.status | status | Product status in Shopify |
| default.totalInventory | totalInventory | Quantity of inventory in stock for the product |
| default.updatedAt | updatedAt | Date and time when the product was last updated |
| description | description | Product description text |
| handle | handle | URL-friendly product handle |
| isBundle | isBundle | Whether the product is configured as a bundle |
| isPublished | isPublished | Whether the product is published on the online store |
| metafields.custom.hardness.value | custom.hardness | Value of the custom hardness metafield |
| onlineStoreUrl | onlineStoreUrl | Canonical online store URL for the product |
| productType | productType | Product type assigned in Shopify |
| publishedAt | publishedAt | Date and time when the product was published to the channel |
| storeContext.country | storeContext.country | Country context used for localized product data |
| storeContext.language | storeContext.language | Language context used for localized product data |
| tags | tags | Tags assigned to the product |
| title | title | Product title |
| vendor | vendor | Vendor or brand that supplies the product |
Variant mappings
Variant: system attributes
| Shopify source field | Item collection attribute | Description |
|---|---|---|
| availableForSale | active | Whether the variant is available for purchase |
| contextualPricing.compareAtPrice.amount | original_price | Compare-at price for the variant in the configured market |
| contextualPricing.price.amount | price | Current price for the variant in the configured market |
| createdAt | launch_date | Date and time when Shopify created the variant |
| image.url | large_image | URL of the variant image |
| image.url | thumb_image | URL of the variant image |
| onlineStoreUrl | url | Canonical online store URL for the variant |
| quantityAvailable | stock_level | Total sellable quantity of the variant for online sales channels |
| selectedOptions[?name=='Color'].value | color | Value of the Color option selected for the variant |
| selectedOptions[?name=='Size'].value | size | Value of the Size option selected for the variant |
| title | title | Variant title |
| vendor | brand | Vendor or brand that supplies the variant |
| vendor | supplier | Vendor or brand that supplies the variant |
Variant: main attributes
main attributes| Shopify source field | Item collection attribute | Description |
|---|---|---|
| availableForSale | availableForSale | Whether the variant is available for purchase |
| barcode | barcode | Barcode assigned to the variant |
| contextualPricing.compareAtPrice.amount | compareAtPrice | Compare-at price for the variant in the configured market |
| contextualPricing.price.amount | price | Current price for the variant in the configured market |
| contextualPricing.price.currencyCode | price.currencyCode | Currency code for the variant's contextual price |
| createdAt | createdAt | Date and time when Shopify created the variant |
| default.taxable | taxable | Whether the variant is subject to tax |
| default.unitPriceMeasurement | unitPriceMeasurement | Unit price measurement details for the variant |
| default.updatedAt | updatedAt | Date and time when the variant was last updated |
| image | image | Image associated with the variant; falls back to the product image when no variant image is available |
| inventoryPolicy | inventoryPolicy | Whether Shopify continues selling the variant when inventory reaches zero |
| quantityAvailable | quantityAvailable | Quantity available for the variant |
| requiresShipping | requiresShipping | Whether the variant requires shipping |
| selectedOptions[].name | selectedOptions.name | Names of the options selected for the variant, such as Color or Size |
| selectedOptions[].value | selectedOptions.value | Values selected for the variant’s options, such as Blue or Large |
| sku | sku | Stock keeping unit assigned to the variant |
| title | title | Variant title |
| variant_id | variant_id | Variant identifier supplied in the source data |
| weight | weight | Weight of the variant |
| weightUnit | weightUnit | Unit used for the variant weight |
Mapping notes
Contextual pricing
contextualPricing contains prices for the country or market configured for the item collection.
| Level | Description |
|---|---|
| Product | Shopify provides minimum and maximum variant prices and, when available, minimum and maximum compare-at prices. |
| Variant | Shopify provides the contextual price and compare-at price for that variant. Shopify also returns a currency code for the contextual price. |
The mappings above expose selected nested amount values as flat main attributes. Compare-at pricing can be absent, so the relevant contextualPricing object or nested property may be null. Contextual prices are refreshed separately from the main product data and may not update at exactly the same time as other catalog fields.
See Shopify's contextual pricing documentation and the Loomi for Shopify integration guide for the market and sync context
System attribute semantics
| Attribute | Meaning | Source mapping | Note |
|---|---|---|---|
active | Bloomreach availability attribute | Product: isPublished Variant: availableForSale | Publication status and purchasability aren’t the same concept |
launch_date | Date/time item first became available for sale | Product: publishedAt Variant: createdAt | Variant createdAt may not reflect when it first became purchasable |
stock_level | On-hand / available-to-sell quantity | Product: default.totalInventory Variant: quantityAvailable | — |
category_paths | Category-path structure for item collections | Custom expression (no direct Shopify field) | Expression output must match the structure item collections expect |
large_image / thumb_image | Product images | Same Shopify image URL for both | No resizing/transformation is applied — thumb_image is not an actual thumbnail |
Source and destination fields
-
brandvs.supplier— both map from Shopifyvendorbut they're distinct item collection attributes. -
Product vs. variant records — a product-level attribute describes the parent product; a variant-level attribute describes one purchasable variant.
-
Fields mapped in both
systemandmain— when a source field appears in both with different destination names, treatsystemas canonical for the reserved attribute, and usemainwhen you need the source-shaped or integration-specific value instead. -
Case sensitivity & nulls — Shopify source paths are case-sensitive and can be absent for some products/variants, particularly: images, SEO fields, metafields, selected options, inventory values, and compare-at prices.
-
Custom metafields — e.g.
metafields.custom.hardness.value→custom.hardness. Availability depends on whether that metafield is configured on the source data.
Updated 43 minutes ago