Configure LinkedOption for Shopify Agentic catalog mapping
LinkedOption can export each product's group ID and option values for Shopify's Agentic channel. After enabling sync in LinkedOption, map these fields in Shopify Catalog so Shopify can group linked products and display their options.
This feature is available on the Advanced, Premium, and Pro plans, with monthly or annual billing. Downgrading below Advanced pauses sync and keeps previously exported data without further updates. After upgrading, enable sync again to refresh the data.
Before you start
Create and publish your product groups in LinkedOption. Open LinkedOption → Settings → Advanced → Integrate with third-party apps, enable Sync product options for Agentic channel mapping, then click Save. Wait for background synchronization to finish. Discard restores the saved setting.
The separate Sync product group data to a public metafield setting is for mobile apps and custom integrations. You do not need to enable it for this tutorial. See Integrate LinkedOption with third-party apps.
Step 1: Enable custom combined listings
Open Shopify Admin → Sales channels → Agentic. In Sources, expand Shopify Catalog, then click Review your product data (the entry may also be labeled Review product data mapping).
In Shopify Catalog Mapping, turn on Custom combined listings, then set Combination method to Product metafield.
Step 2: Open the combination metafield picker
Click Combination metafield. Under Product metafields, click View more to see the available fields.
Step 3: Find LinkedOption's Agentic fields
Choose Choose a field from LinkedOption Agentic Product Options.
Step 4: Select Group ID
Select Group ID. This shared value tells Shopify which products belong to the same LinkedOption group.
Step 5: Add an option mapping
Confirm Combination metafield now reads LinkedOption Agentic Product Options > Group ID. Under Options, click Add options to add a row.
Step 6: Select the option source
In the new row's Option dropdown, find Product metafields and choose Choose a field from LinkedOption Agentic Product Options. Select the dimension you want to expose, such as Colour, Finish, or Size.
Use your own configured option names. Color and Colour are separate fields, so choose the spelling used in your product groups. For subgroup-based groups, select the actual configured subgroup field names.
Step 7: Set display names, review, and save
Enter the customer-facing Display name for each row. Repeat Add options for the dimensions you need. This example maps Colour, Finish, and Size to the same display names.
Review Shopify's product check results. Combined means products were grouped; left separate means Shopify did not find a shared grouping value; need review means grouped variants have duplicate option combinations. Click need review to inspect flagged products and resolve conflicting combinations.
Use the Grouping tab and product picker to inspect representative groups, then click Save. The counts in the screenshot are examples from that store; your results will differ. Shopify processes saved changes with a delay.
The product picker changes the preview; the mapping applies across the store. Each row has a fixed display name. Standard Shopify variant options are added automatically. The preview does not guarantee the final presentation in an AI channel. See Shopify Catalog Mapping.
How LinkedOption exports Agentic data
When Agentic option sync is enabled, LinkedOption creates the following data independently of the complete group JSON export:
Resource | Identifier | Purpose |
|---|---|---|
Product metafield |
| Reference named LinkedOption Agentic Product Options |
Metaobject definition |
| Shared field structure within this store |
Metaobject record | One per product and group | That product's assigned option values |
Required field |
| Same value for members of the same group |
Optional fields | Named Color, Size, Material, etc. | Single-line text values for that product |
The field keys are stable hashes of normalized option names, beginning with option_. Select the readable field names in Catalog Mapping; do not type or invent the keys. Names differing only in casing, repeated whitespace, or Unicode normalization reuse a field. Different names such as Color and Colour remain separate.
For example, one shared definition can contain Color, Size, and Material. Each record only fills the fields relevant to its product:
Product | Group ID | Color | Size | Material |
|---|---|---|---|---|
Red top | lo-group-100 | Red | — | — |
Blue top | lo-group-100 | Blue | — | — |
Red small T-shirt | lo-group-200 | Red | Small | — |
Blue large T-shirt | lo-group-200 | Blue | Large | — |
Oak chair | lo-group-300 | — | — | Oak |
Walnut chair | lo-group-300 | — | — | Walnut |
A dash means the optional field has no value. LinkedOption does not write the string "null", and clears obsolete values when a product's dimensions change. Subgroup-based groups use the actual configured subgroup names as Catalog fields. Each product fills only the fields for subgroups it belongs to, using its linked option label. The complete group JSON still keeps subgroups as display categories. A display category is not necessarily a variant dimension; select only suitable fields in Catalog Mapping.
Check mixed groups
Check a Color-only group, a Size-only group, and a Color + Size group using the same mapping. Fields not applicable to a group are left unset. Shopify's exact handling of all-empty custom dimensions and their interaction with native product variants still needs to be verified for your catalog; an empty field is not a promise that every AI channel will hide that option.
If Shopify reports duplicate option combinations, check that each selectable product and its native variants can be distinguished by the configured dimensions. A product left separate is not proof that the public sync failed. The Grouping preview does not guarantee the final presentation in an AI channel. See Shopify Catalog Mapping.
Field maintenance and limits
LinkedOption checks option names across all product groups, including drafts, while Agentic support is enabled. It removes a managed option field only when no group uses that dimension anymore. Unused fields are removed before new ones are added. Unrelated merchant-added fields are preserved.
Shopify allows 40 fields per metaobject definition. Group ID uses one, leaving up to 39 option fields when there are no additional custom fields. If the active field set exceeds the limit, synchronization reports an error; it does not silently drop dimensions. See Shopify's metaobject limits.
The earlier synthetic Linked product field is removed on the next sync unless a group explicitly uses that name. Review and replace any Mapping row pointing to it.
Deleting the last group that uses a dimension, or renaming that dimension everywhere, can remove its field. Review any Catalog Mapping rows that refer to removed fields. If that name is used again later, LinkedOption recreates its field; you may need to select it again in Catalog Mapping.
The two settings are independent. Turning Sync product options for Agentic channel mapping off and saving removes only its product-specific records, references, and managed option fields in the background. It does not stop or delete the complete group JSON export. Turning Sync product group data to a public metafield off stops only that export and keeps its existing data by default. Selecting Also remove the synced product group data removes only the shared product group export; Agentic option sync continues if enabled.
Agentic option fields currently use the original option values. They do not copy the localized JSON translations or provide market-specific values. The full group JSON retains its existing translation support. Product availability, prices, and the AI channel's final language and presentation are handled separately by Shopify.
Updated on: 14/10/2026
Thank you!