Why does Acumatica fail with “Shopify supports only up to 3 product options”?
Acumatica models a product family as a A matrix item is Acumatica’s way of describing a product that comes in variations, such as a shirt in four sizes and three colours. Acumatica calls the parent a template item and generates a stock item for each combination. with attributes, and generates a stock item, the A matrix item is Acumatica’s way of describing a product that comes in variations, such as a shirt in four sizes and three colours. Acumatica calls the parent a template item and generates a stock item for each combination., for every combination. Acumatica does not limit you to three attributes. Shopify does limit a product to a small number of options, exposed in its Admin API as the shop resource limit maxProductOptions, and three is the number the Acumatica connector’s error message quotes back at you.
The verbatim error, from Acumatica community thread 18873, is: “Product options could not be created in Shopify. There are 1 variant types in the MISIML template item, but Shopify supports only up to 3 product options.” Read that carefully, because the message is misleading. It fires for too many attributes and for too few, and the count it prints is the count it found, not the count it wanted.
The floor matters as much as the ceiling. Acumatica wants at least two attributes on a template item. A product family that varies on one dimension only, say length, is a legitimate thing to sell and an illegitimate template item. The workaround offered in that thread is blunt and it works: “Create dummy variables for these and it solved our problem. Your dummy variable can be something trivial like color and it can be the same for every variant, but it has to be there.”
Checked against: Community 18873: template item sync error, three product options, Shopify Admin GraphQL Product object: options limited by Shop.resourceLimits.maxProductOptions
What do you do with a product that genuinely has four attributes?
A fall-arrest harness in four sizes, two colours, two attachment styles and with or without a back brace is four dimensions, and no amount of configuration makes Shopify hold it as one product. The community answer in thread 18873 is to split the template: one template item with the back brace, one without, each within the three-option ceiling. That is a catalogue decision, not a technical one, and it lands on whoever owns merchandising rather than on IT.
The options, ranked roughly by how much they cost you afterwards, are below. Each one has a real downside, and the one that looks cheapest at build time is usually the one that costs most in catalogue maintenance.
Split the template item into two or more templates along the least interesting attribute. Cheapest to build, and it fragments the product page so a buyer has to find the other half.
Collapse two low-cardinality attributes into one compound option, for example “Black / With brace”. Keeps one product page, and the option values multiply and stop being filterable.
Move one attribute out of the variant model entirely and sell it as a separate line item or an add-on. Clean in Shopify, and it means the ERP and the storefront no longer agree on what a product is.
Take the configuration off the variant model and into a configurator on the front end that resolves to a matrix item at add-to-cart. This is the honest answer for a genuinely configurable product, and it is a development project rather than a setting.
Checked against: Community 18873: splitting template items to stay under the option ceiling
Why does the Acumatica template sync keep reordering your Shopify variants?
Because it sorts them, every time, and it does not ask. A merchant in Acumatica community thread 22934 explained why the order matters to him: variants are arranged cheapest first, or with the colour that should appear on collection pages first, because Shopify defaults a collection tile to the first variant of a product. Template sync re-sorted them even when nothing had changed.
The answer from Acumatica staff in that thread is unusually direct: “we make the sort order of variants by the following order: Option1 → Option2 → Option3.” It was reported on Acumatica 2023 R1 and the thread indicates the behaviour persisted through at least 24R1, with Acumatica treating a configurable sort order as a future enhancement rather than something you can switch off.
Two ways out are offered. Override the MapVariantPositions method on the SPTemplateItemProcessor graph through a customization, which means owning a customization against a connector graph. Or set the column and row configuration and the sort order on the Item Class so that Acumatica’s sort happens to produce the order you want in Shopify. The second is free and constrains your merchandising to whatever your attribute values sort as.
Checked against: Community 22934: matrix items overwriting variant order on Shopify
What are the two errors that catch people after an upgrade?
The first is version-specific and recent. On 25R1, template sync started failing with “At least one option value is duplicated” and “Error mapping types… Input Destination Member: Options”. Per the Acumatica Support analysis quoted in community thread 30860, the Commerce Connector rejects the template if the attribute contains any duplicate value descriptions at all, even when the item being synced uses none of the duplicated values. The reporter’s SIZE attribute had unused duplicate descriptions; the item used Large, Medium and X-Large, none of them duplicated, and it still failed. Deduplicating the attribute value descriptions fixed it. The poster notes this behaved differently on 23R2, so treat it as a validation change introduced with 25R1 and re-test it on your own release.
The second is worse because it is quiet. In community thread 20979, from January 2024, matrix items were simply missing from Shopify while the template and every matrix item were active and had stock. Escalation to Acumatica support concluded “it needs a bug fix in the Shopify connector”. Deleting and saving the sync record cleared it temporarily, and the reporter says “The error often comes back though”. If you have a catalogue where products vanishing from the storefront costs you real money, you need a count reconciliation between Acumatica and Shopify running on a schedule, because the connector will not tell you.
| Criterion | Observed on | What it actually means |
|---|---|---|
| “Shopify supports only up to 3 product options” | Release not stated in thread 18873 | Attribute count on the template item is wrong. Too many attributes, fewer than two attributes, or a Shopify variant with no matching matrix item in Acumatica. |
| “At least one option value is duplicated” / “Error mapping types” | 25R1, and reported as behaving differently on 23R2 | An attribute somewhere contains duplicate value descriptions. The item being synced does not have to use them. |
| Variant order changes with no catalogue change | Reported on 2023 R1, persisting through at least 24R1 | Working as designed. The connector sorts Option1 then Option2 then Option3 on every template sync. |
| Matrix items missing from Shopify, no error | Reported January 2024, release not stated | Confirmed by Acumatica support as needing a connector fix. Clearing the sync record is a temporary measure, not a resolution. |
Checked against: Community 30860: Shopify Plus 25R1 template sync error, Community 20979: missing matrix items in the Shopify sync
When should you stop trying to make matrix items work?
If your product families run to four or more genuine attributes across most of the catalogue, the variant model is the wrong container and every hour you spend on template sync is buying you a worse catalogue. That is the point at which a configurator, a Middleware is a layer of software that sits between the ERP and the storefront, translating and enforcing rules that neither system holds on its own. It can be a hosted integration platform or a custom service. layer that resolves a configuration to a matrix item, or a platform with a deeper product model earns its cost.
If your product families are two or three attributes and the pain is variant order and the occasional missing item, matrix items are fine and what you actually need is monitoring. A nightly count of published variants in Shopify against active matrix items in Acumatica catches thread 20979’s failure mode the morning it happens instead of the quarter it happens.
We cannot tell you which of those you are from a page. Which one you are depends on the shape of your catalogue, and that is one of the things the Celeste diagnostic asks about first.
Common questions
- How many product options does Shopify actually allow?
- Shopify’s Admin GraphQL documentation does not hard-code the number in the Product object. It says the limit is defined by the shop resource limit maxProductOptions, which you can query for your own store. Three is the figure the Acumatica connector prints in its error message and the figure the community threads work around, so plan for three unless you have queried your own shop and found otherwise.
- Can I stop the Acumatica connector from reordering my Shopify variants?
- Not with a setting, as of the behaviour reported on Acumatica 2023 R1 and persisting through at least 24R1. Acumatica staff confirmed the connector sorts variants Option1 then Option2 then Option3 on every template sync. The two options given in community thread 22934 are to override MapVariantPositions on the SPTemplateItemProcessor graph in a customization, or to arrange your Item Class column, row and sort order so Acumatica’s sort produces the order you want.
- My template item has only one attribute. Why does it fail?
- Acumatica requires at least two attributes on a template item, so a single-dimension family such as length-only fails the same validation that a four-attribute family fails. The workaround in Acumatica community thread 18873 is to add a dummy attribute with the same value on every variant, which satisfies the check without changing what the customer sees. It is inelegant and it is the answer the community landed on.
- Why did template sync start failing after we upgraded to 25R1?
- Most likely because 25R1 validates attribute value descriptions more strictly. Per Acumatica Support’s analysis in community thread 30860, the connector rejects a template item when the attribute contains duplicate value descriptions anywhere, even if the item being synced uses none of them. The fix is to deduplicate the descriptions on the affected attributes. The reporter states the same data synced on 23R2.
- How do we catch matrix items that go missing without an error?
- Reconcile counts on a schedule, because the connector does not raise anything. Compare the number of active matrix items with Export to External System enabled in Acumatica against the number of published variants in Shopify, per template, nightly. Acumatica community thread 20979 shows support confirming this as a connector bug, with clearing the sync record as a temporary measure that the reporter says stops working again.
Last updated 2026-08-20. Facts on this page last checked against source 2026-08-20.