> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://help.linkedoption.com/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# 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.

![Open LinkedOption Settings, enable Agentic option sync, and click Save](https://storage.crisp.chat/users/helpdesk/website/-/b/7/5/a/b75ae5b79c0f0000/codex-clipboard-90388581-94b5-_1oxt3bt.png)

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](https://help.linkedoption.com/en/article/integrate-linkedoption-with-third-party-apps-4x5wz1/).

## 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**).

![Open Agentic, expand Shopify Catalog, and click Review your product data](https://storage.crisp.chat/users/helpdesk/website/-/b/7/5/a/b75ae5b79c0f0000/codex-clipboard-53742498-bcc1-_1m2z9hi.png)

In Shopify Catalog Mapping, turn on **Custom combined listings**, then set **Combination method** to **Product metafield**.

![Enable Custom combined listings and select Product metafield](https://storage.crisp.chat/users/helpdesk/website/-/b/7/5/a/b75ae5b79c0f0000/codex-clipboard-a670beee-af7a-_1z016j9.png)

## Step 2: Open the combination metafield picker

Click **Combination metafield**. Under **Product metafields**, click **View more** to see the available fields.

![Open Combination metafield and click View more under Product metafields](https://storage.crisp.chat/users/helpdesk/website/-/b/7/5/a/b75ae5b79c0f0000/codex-clipboard-b0541795-1b78-_165su46.png)

## Step 3: Find LinkedOption's Agentic fields

Choose **Choose a field from LinkedOption Agentic Product Options**.

![Choose a field from LinkedOption Agentic Product Options](https://storage.crisp.chat/users/helpdesk/website/-/b/7/5/a/b75ae5b79c0f0000/codex-clipboard-b0da22f0-2530-_owcvuz.png)

## Step 4: Select Group ID

Select **Group ID**. This shared value tells Shopify which products belong to the same LinkedOption group.

![Select Group ID as the grouping field](https://storage.crisp.chat/users/helpdesk/website/-/b/7/5/a/b75ae5b79c0f0000/codex-clipboard-6d25aa34-3641-_1vvo3ug.png)

## 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.

![Group ID selected and a new option mapping row added](https://storage.crisp.chat/users/helpdesk/website/-/b/7/5/a/b75ae5b79c0f0000/codex-clipboard-9c885c80-1d30-_1bx26bn.png)

## 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**.

![Choose LinkedOption Agentic Product Options as the option source](https://storage.crisp.chat/users/helpdesk/website/-/b/7/5/a/b75ae5b79c0f0000/codex-clipboard-6c889adf-d98e-_1uaolxz.png)

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.

![Completed Colour, Finish, and Size mappings with Shopify product check results](https://storage.crisp.chat/users/helpdesk/website/-/b/7/5/a/b75ae5b79c0f0000/codex-clipboard-c641e891-182c-_18mgg3i.png)

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](https://help.shopify.com/en/manual/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 | `linked_options.catalog_product` | Reference named **LinkedOption Agentic Product Options** |
| Metaobject definition | `linked_options_catalog_product` | Shared field structure within this store |
| Metaobject record | One per product and group | That product's assigned option values |
| Required field | `group_id` | 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](https://help.shopify.com/en/manual/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](https://shopify.dev/docs/apps/build/metaobjects/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.