Product structure management
This section explains how product structures are handled in the Akeneo app for Shopify, and how to enable the options to split product models by intermediate variation level, by variant, or using Shopify Combined Listings.
What is a product structure?
The product structure defines how products, product models, and variants are synchronized and organized in Shopify.
By default, the app mirrors the PIM structure in a 1:1 synchronization:
- A simple product in Akeneo becomes a simple product in Shopify.
- A two-variation axis product model in Akeneo becomes a two-variation axis product model in Shopify.
In addition to this default 1:1 mirroring, the app offers three alternative structures, described below: splitting product models at the intermediate level, splitting each variant as a separate product, and splitting product models using Combined Listings.
Please note that Shopify supports a maximum of 3 product options (variation axes) per product, and the app follows this limitation.
If your product models contain more than 3 variation axes and use a two-level variation structure (sub-product models and variants), you can use the intermediate-level split by disabling the "Create intermediate-level variation axes as options" setting, provided that the lowest variation level (variants) contains no more than 3 variation axes.
With this configuration, only the variation axes from the lowest level will be created as Shopify product options, allowing the product to remain within Shopify's 3-option limit.
Alternatively, splitting each variant as a separate product removes this constraint entirely, since each resulting product has a single variant and no product options.
The same 3-option limit also applies to the combined listing parent.
Splitting product models at the intermediate level
For product models with two levels of variation, the app offers the possibility to split products at the intermediate variation level.
This means that sub-product models can be synchronized as separate products in Shopify.
Example:
If your PIM product model has two variation axes on two variation levels - Color and Size:
- By default, all colors and sizes are grouped under a single product in Shopify.
- With the split option enabled, each color is created as a separate product in Shopify, with its sizes as variants.
.png)
This approach can help:
- Increase product visibility on collection pages.
- Improve merchandising and offers by highlighting each product variation individually.
Splitting each variant as a separate product
For product models with one or two levels of variation, the app also offers the possibility to synchronize each Akeneo variant as its own standalone product in Shopify, instead of grouping variants under a single product (or under one product per intermediate level). Each resulting Shopify product has a single variant, corresponding to one specific combination of variation axis values.
Example:
If your PIM product model has two variation axes - Dimensions and Color - on a single variation level (for example, a chest of drawers with these two axes):
- By default, all dimensions and colors are grouped under a single product in Shopify, with each Dimensions/Color combination as a variant.
- With this split option enabled, each Dimensions/Color combination is synchronized as its own separate, single-variant product in Shopify.
This behavior is the same for product models with two variation levels: every Akeneo variant, regardless of the level it belongs to, is synchronized as an individual product.
This approach can help:
- Give each variant its own dedicated product page and URL in Shopify.
- Simplify catalog structures when variants are meant to be merchandised, priced, or sold independently.
Because each resulting product has a single variant, no product options are created in Shopify for this structure. This mode is not affected by Shopify's 3-option limit mentioned above.
This option is disabled by default and can be enabled on request by our product team. To request this, please contact our support team via this link.
Splitting product models using Combined Listings
Shopify Combined Listings let you display several separate products as a single listing on your storefront. A combined listing is made of:
- A combined listing parent, which carries the options your customers pick from (for example, Color). The combined listing parent is a Shopify product of its own, with no variants.
- Several child products, each corresponding to one value of these options, with its own product page, media, and variants.
With this structure, the app splits your product models into separate Shopify products, just like the other split options, and then automatically groups them under a combined listing parent. Your customers see a single product with an option selector, while each child product keeps its own content in Shopify.
Product models with two variation levels
For product models with two levels of variation, the split happens at the intermediate level:
- The root product model becomes the combined listing parent in Shopify.
- Each sub-product model becomes a child product in Shopify, with its variants.
- The intermediate-level variation axes become the options of the parent.
Example:
If your PIM product model has two variation axes on two variation levels - Color and Size:
- Each color is created as a separate product in Shopify, with its sizes as variants.
- All these products are grouped under one combined listing parent, which offers Color as an option on your storefront.
Product models with one variation level
By default, product models with a single level of variation are not combined: they are synchronized as a single product with its variants, as in the 1:1 structure.
If you enable the Combine product models with a single variation level setting:
- The product model becomes the combined listing parent in Shopify.
- Each variant becomes a separate child product in Shopify.
- The variation axes become the options of the parent.
This setting is disabled by default. Product models with two variation levels are always combined, whatever this setting.
These combined listings are built during product synchronizations: each child product is synchronized with your Products mapping, like a standalone product.
What is synchronized on the combined listing parent?
When the Split PIM product models using Combined Listings structure is selected, a Combined Listings tab is available in the app, where you can map the data synchronized on the combined listing parent:
- Combined listing parent fields: the Shopify fields of the combined listing parent, including its status, mapped from the Attributes of the root product model in Akeneo. The list of supported fields is available here.
- Media: the images and assets of the combined listing parent. Shopify also displays the featured media of each child product on the combined listing parent: the app keeps these media and only removes the media it uploaded itself.
Metafields are only synchronized on the child products by default. If you also want them on the combined listing parent, enable the Push metafields on the combined listing parent setting. This setting covers the metafields mapped from Attributes and from reference entities (metaobjects).
If no title is mapped for the combined listing parent, the code of the root product model is used as its title.
If no field is mapped for the combined listing parent, the app creates it once and then never updates its fields, so you can edit them directly in Shopify. The app still manages its options, its child products and its publication on each synchronization.
How the app maintains combined listings
- When a child product is removed from its product model in Akeneo, it is detached from the combined listing on the next full synchronization. The product is kept in Shopify. Delta synchronizations never detach child products.
- Child products added manually in Shopify are never detached by the app.
- If you delete a combined listing parent in Shopify, the app recreates it on the next synchronization.
Combined Listings limits
The app follows the limits set by Shopify on combined listings. For each combined listing:
| Limit | Maximum |
|---|---|
| Child products | 60 |
| Options on the combined listing parent | 3 |
| Variants across all the child products | 2,000 |
If a product model exceeds one of these limits, the combined listing is not updated and an error is displayed in the synchronization report.
This approach can help:
- Give each variation its own product page, URL, and media, while still displaying a single product on your storefront.
- Keep a clean catalog on collection pages, without losing the benefits of split products.
Combined Listings are a Shopify Plus feature: this structure is only available for Shopify Plus stores.
The app creates combined listings without the Shopify Combined Listings app, and you can view them in your Shopify admin without it. This Shopify app is optional: it lets you filter your combined listings and create combined listings manually from its interface.
This option is disabled by default and can be enabled on request by our product team. To request this, please contact our support team via this link.
Prerequisites
Splitting at the intermediate level: this option is only available for product models with two levels of variation.
Product models with a single level of variation, even if they include several variation axes, cannot be split at the intermediate level.
Splitting each variant as a separate product: this option is available for product models with one or two levels of variation, regardless of how many variation axes they use.
Splitting using Combined Listings: this option is only available for Shopify Plus stores. If your store is no longer on Shopify Plus, synchronizations stop with an error until you select another product model structure. The Shopify Combined Listings app is not required. This option applies to product models with two levels of variation, and to product models with one level of variation when the Combine product models with a single variation level setting is enabled.
Two variation axes ≠ two variation levels.
- A variation axis is the attribute used to create variations of a product (e.g., Color, Size, Material).
- A variation level defines how many layers of variation a product model has in Akeneo.
Please note that, for security reasons, the product model structure can only be changed if no product model synchronization has been triggered on this store.
If you need to switch between structures for testing purposes, our team can disable this restriction by enabling a feature flag.
To request this, please contact our support team via this link.
Recommendations
Before changing this setting, please keep in mind:
- Duplicates may be created in Shopify if the same products are already synced with a different structure.
- The app does not delete products in Shopify when you switch structures.
We recommend:
- Reviewing your product mapping and sync settings.
- Running a test sync to validate the results before applying this change in production.
How to enable the product model split?
Follow these steps to configure product models:
- In your Akeneo App for Shopify, navigate to the Configuration page.
- In the Product model structure section, select one of the following options: Keep PIM product model structure (1:1), Split PIM product models by intermediate variation level, Split each PIM variant as a separate product, or Split PIM product models using Combined Listings.
- Confirm your change.
If you selected Split PIM product models by intermediate variation level, also configure the following additional settings:
- Define if you want to create a sibling product reference metafield between the separate products, allowing you to easily group products with the same parent in Shopify - this option is disabled by default.
- Define if you want to include the current split product in sibling products in Shopify, allowing you to easily group products on your storefront - this option is disabled by default, so the current product is not in the sibling product list.
- Define if you want to create intermediate-level variation axes as options in Shopify, allowing you to keep all variation axes in Shopify - this option is disabled by default, so intermediate-level variation axes are not created.
If you selected Split each PIM variant as a separate product, no additional setting is required.
If you selected Split PIM product models using Combined Listings, also configure the following additional settings:
- Define if you want to combine product models with a single variation level, allowing each of their variants to be synchronized as a child product of a combined listing - this option is disabled by default, so these product models are synced as a single product with their variants.
- Define if you want to push metafields on the combined listing parent - this option is disabled by default, so only the child products receive the mapped metafields.
Save your configuration once you are done.
If you selected Split PIM product models using Combined Listings, open the Combined Listings tab to map the fields and media of the combined listing parent, then save your mapping.
By enabling sibling product preferences, the app will automatically create a new product reference metafield called “Sibling product” and assign it the values of other products that share the same parent. This setting is only available for the intermediate-level split.
If you disable this setting, or switch to the Keep PIM product model structure (1:1) or Split PIM product models using Combined Listings structure, the “Sibling product” metafield definition and all its values are deleted from Shopify.
Attributes defined at the parent or intermediate level in Akeneo are synced as product-level attributes in Shopify.
If you want each split product to have its own title or specific assets, the corresponding PIM attribute must be set at the intermediate level in Akeneo. This applies to the intermediate-level split and to Combined Listings.
For combined listings built from product models with one variation level, each child product uses the attribute values of its variant.
Please note the intermediate-level split will be effective for all two-variation level product models regardless the variant family.
Similarly, once enabled, splitting each variant as a separate product will be effective for all eligible product models regardless the variant family or the number of variation levels.
The same applies to Combined Listings: all two-variation level product models are combined regardless the variant family, as well as all single-variation level product models if the Combine product models with a single variation level setting is enabled.