Configurable product import over REST in four steps: global configurable attribute, option IDs not labels, simple children carrying the value, then the parent. Parent first gives an unbuyable product page with no error

Magento Product Import via REST: What Actually Breaks

This article leads with the endpoint everyone starts on and should not finish on: POST /rest/V1/products is the first endpoint every Magento 2 and Adobe Commerce integrator finds and the last one they should build a catalog sync on. It works in the PoC. It works for the 200-SKU pilot. Then the real ERP export arrives with 48,000 SKUs, twelve store views, and a nightly delta of 6,000 price changes, and the sync takes nine hours, leaves store-scope overrides nobody can explain, and multiplies pub/media by the number of runs.

None of that is a bug. It is the ProductRepository behaving exactly as designed, driven by a client that assumed REST semantics rather than EAV semantics. This is the list of places that gap shows up.

This article covers the structural half: getting products, their attributes, their media and their variants into Magento correctly. That is deliberately the part to build first — a catalog that is loaded but not yet priced, stocked or categorised is already enough for the theme team to lay out real pages against, which unblocks four workstreams while the integrator carries on. The commercial and taxonomy halves are separate work and separate articles: Prices and Stock via REST and Magento Categories via REST. The rules that apply to every family regardless of entity live in the pillar, Magento ERP Integration.

About the SQL in this document. Every query below is a diagnostic, for an integrator with a database console who is trying to find out what an import actually did. None of it belongs in an integration, a module, a cron job, or anything that runs unattended. Raw SQL against the catalog tables bypasses the repository layer and therefore every indexer trigger, cache invalidation, plugin, and scope rule that makes the data correct — which is the same mistake, one layer down, that this whole document is about. It is also schema-coupled: row_id versus entity_id alone differs between Open Source and Commerce with staging, and these tables change between releases.

Read with SQL when you need the truth fast. Write with the API, always. Where a query here reveals damage, the fix is a data patch or an API call, not an UPDATE.

TL;DR — POST /rest/V1/products is the first endpoint every integrator finds and the last one they should build a catalog sync on. None of what breaks is a bug — it is ProductRepository behaving exactly as designed, driven by a client that assumed REST semantics where EAV semantics apply. A partial update is not partial the way you expect, configurable variants carry an ordering requirement, scope decides whether a write lands globally or per store view, and links are replaced rather than merged.

Magento 2 or Adobe Commerce? Tested on Magento Open Source 2.4.8-p5. The REST API is the same in Adobe Commerce on cloud infrastructure and on-premises; only Adobe Commerce modules such as B2B or content staging add or change endpoints. Adobe Commerce as a Cloud Service is a separate, smaller REST surface with IMS authentication, so check its reference before reusing a route from here. The SQL diagnostics are Open Source only: with content staging, Adobe Commerce keys catalog rows on row_id instead of entity_id.

Why this matters now

2.4.9 (GA 12 May 2026) is the first release under Adobe’s annual cadence, and it is a platform modernization release rather than a feature release — PHP 8.5, Symfony Cache in place of Zend_Cache, native OAuth, OpenSearch 3, and the largest bug-fix count of any 2.4.x release. Two consequences for integrations specifically:

  • CAPTCHA enforcement moved onto API account-creation endpoints. Any unauthenticated registration flow in an integration breaks on upgrade. Catalog imports are unaffected, but the same integration codebase usually owns both.
  • Native OAuth replaced the third-party library. Token handling in long-running import clients is worth re-testing rather than assuming.

If you are still on 2.4.6, support ended in August 2026 — that is the more urgent problem than any of this.

Provenance note. Everything in this paragraph is release-note reading, not something this document tested. The verification pass behind the rest of the article ran on a 2.4.8-p5 sandbox, so no 2.4.9 claim above — the GA date, the PHP and OpenSearch versions, the cache and OAuth swaps, the CAPTCHA change, the 2.4.6 end-of-support date — has been executed against a running install. Check the release notes before repeating any of it.

The baseline nobody should ship

for each row in erp_export.csv:
    PUT /rest/V1/products/{sku}   (full payload, images base64, stock inline)

Serial, synchronous, full-product saves, media on every run, one HTTP request per SKU. Every request is a full Magento bootstrap on the same PHP-FPM pool the storefront uses. At ~400 ms per save you are at 5.3 hours for 48k SKUs, and that is before reindex.

Everything below is a specific way this shape hurts.

The cross-cutting rules live in the pillar

Four things this article used to carry apply to every endpoint family, not just products, so they moved to Magento ERP Integration: Products, Customers, Orders:

  • Store-code scope and the silent default-store override — the most expensive default in the API, and the reason a scopeless update writes a translation nobody asked for.
  • Restoring inheritance, which no ordinary write can express — and BroCode_ScopeReset, which adds it to the REST API using the CSV importer’s own sentinel.
  • Indexer mode and throughput — including that async/bulk needs no message broker, and that acceptance is not completion.
  • Credentials, deadlocks and worker starvation.

Everything below assumes them.

"Partial update" is not partial the way you think

The tradeoff running through everything below is between the convenience of one endpoint that accepts an entire product and the precision of narrow endpoints that accept one thing each. The wide endpoint is faster to write and is the source of nearly every defect in this article.

ProductRepository::save() merges custom_attributes — attributes you omit keep their previous value. That sounds forgiving until you realise the opposite is true for the collection-shaped fields:

  • extension_attributes.website_ids — sending a shorter array unassigns websites. Omitting it is fine on update, and on every create except one: measured on 2.4.8-p5 with two websites, a create through the all scope with no website list assigns the product to every website, while the scopeless and store-view creates each assign one. Send it explicitly on creates and the question does not arise — the payloads later in this article do.
  • extension_attributes.configurable_product_links — replaced wholesale.
  • product_links (related/upsell/cross-sell) — replaced wholesale, across all link types at once; see below.
  • media_gallery_entries — replaced wholesale, and sending them on a product save is where duplication starts. See Magento Product Media via REST.

The practical consequence: you cannot clear an attribute by omitting it. To null out a text attribute you send it explicitly with an empty string; for a select you send the option id you designated as "unset". An ERP that stops exporting a field does not clear it in Magento, and the stale value persists for years.

The rest of the catalog has its own articles

Four things an ERP feed also sends were split out, because they are separable work and because the shop does not need them to start looking like a shop:

  • Magento Product Media via REST — duplication on every run, the gallery/role scope mismatch, and the cross-store deletion refusal.
  • Prices and Stock via REST — the narrow endpoints that skip a product save entirely, their two opposite error models, MSI versus legacy stock.
  • Magento Categories via REST — an entity with no natural key, the two assignment paths and their opposite semantics, anchors.
  • Product Attributes via REST — types, options, translations, swatches, and what happens to properties third-party modules add.

The cross-cutting rules in the pillar — scope, credentials, throughput, idempotency, the error-model warning — apply to all four.

Configurables: order of operations

Nothing about the configurable API is forgiving about sequence:

1. The configurable attribute must exist, be global scope, and have is_global = 1 plus be usable for configurables.

2. Attribute options must exist, and you must send option IDs, not labels. Labels are a display concern; sending "Rot" where the API wants 142 fails or silently no-ops depending on the attribute type.

3. All simple children must exist and already carry the attribute values.

4. Only then create the parent with extension_attributes.configurable_product_options and configurable_product_links.

Sending the parent first produces a configurable with no options that renders as an unbuyable product page. The failure is not loud — no exception, just a broken PDP.

Multiselects are stored comma-joined by option ID. Dates want Y-m-d H:i:s. Booleans are 1/0, not true/false — the framework will coerce, but not consistently across attribute backends.

Validated configurable payloads

Run on 2.4.8-p5 against sample data, using the color attribute (attribute_id 93, global, select) and its real option IDs — 49 Black, 50 Blue.

Step 1 — children first, each carrying the attribute value, and in an attribute set that actually contains the attribute:

curl -s -X POST "$BASE/rest/all/V1/products" \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"product":{
    "sku":"ERP-1001-BLACK","name":"Kettle Black","attribute_set_id":9,
    "type_id":"simple","price":25,"visibility":1,"status":1,
    "extension_attributes":{"website_ids":[1]},
    "custom_attributes":[{"attribute_code":"color","value":"49"}]}}'

Step 2 — the parent, then its option, then the links:

# parent, same attribute set as the children
curl -s -X POST "$BASE/rest/all/V1/products" \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"product":{"sku":"ERP-1001","name":"Kettle","attribute_set_id":9,
       "type_id":"configurable","visibility":4,"status":1,
       "extension_attributes":{"website_ids":[1]}}}'

# the configurable option — value_index entries are option IDs
curl -s -X POST "$BASE/rest/all/V1/configurable-products/ERP-1001/options" \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"option":{"attribute_id":"93","label":"Color","position":0,
       "is_use_default":true,
       "values":[{"value_index":49},{"value_index":50}]}}'
# -> 200, body: "297"   (the new option id, as a JSON string)

# one call per child
curl -s -X POST "$BASE/rest/all/V1/configurable-products/ERP-1001/child" \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"childSku":"ERP-1001-BLACK"}'
# -> 200, body: true

GET /V1/configurable-products/{sku}/children reads the result back and is the check to run after every import.

What failure actually looks like. Four cases measured, and only one of them is loud in a useful way:

SentResult
parent + options created before any child exists200. Option id returned, children is []. This is the unbuyable PDP — no exception anywhere
"value_index":"Blue" (a label)400 — The "Blue" value's type is invalid. The "int" type was expected. Clear, because it is a type error
"value_index":999999 (numeric, nonexistent)200. Returns an option id, and GET .../options/{id} then shows "values": [] — the option was created empty. Silent data loss
linking a child whose attribute value is missing400 — The child product doesn't have the "%1" attribute value. with "parameters":["color"]

That last message has the same unresolved-placeholder problem as the price endpoints — %1 is never interpolated into message, and the attribute name is only in parameters. It is worth treating as a general rule for this API: read parameters, never just message.

Relinking a child that is already attached returns 400 "The product is already attached." — so POST .../child is not idempotent, unlike POST /V1/categories/{id}/products. Two adjacent link endpoints, two different retry semantics.

The failure that cost the most time here was none of the above. The children were first created in attribute set 4 (Default) with custom_attributes: [{"attribute_code":"color","value":"49"}]. The API returned 200. The value was never stored — color is not a member of set 4 in sample data, only of Top, Bottom, Bag, Gear and similar. Every later step then failed with the unhelpful %1 message, pointing at the link rather than at the real cause four requests earlier. See the attribute-set section below, which this corrects.

Store-view scope is not where people expect it

The scope rules above are only useful if you know which attributes they apply to. Measured on 2.4.8-p5 from catalog_eav_attribute.is_global:

ScopeAttributes
Store View (0)name, description, short_description, meta_title, url_key, visibility
Global (1)price, cost, weight
Website (2)status, tax_class_id

Two of these catch people out. status is website-scoped, not store-view — you cannot disable a product on one store view and leave it enabled on its sibling; the smallest unit is the website. And price is global by default, so the store_id on a base-prices row does nothing until catalog price scope is switched to website in configuration.

Everything in the Store View row is a translation target, which means every one of them is a candidate for the silent default-store override described above. An ERP that sends name and description through a scopeless route is writing translations nobody asked for.

status: 0 is accepted, and it is not "Disabled"

The scope table above has a second edge on it that is easy to walk into, because both halves look harmless on their own.

status has exactly two legal values. Magento\Catalog\Model\Product\Attribute\Source\Status defines STATUS_ENABLED = 1 and STATUS_DISABLED = 2, and getOptionArray() returns those two and nothing else. There is no 0. Plenty of source systems disagree — an ERP that carries an active boolean and a mapping layer that writes (int) $active produces 1 for active and 0 for inactive, and 0 looks like the obvious encoding for "off" to everyone who has never read that class.

The API does not object. status is a first-class typed property on ProductInterface — @param int $status — not a custom_attribute, so it is cast to an integer and written straight through. The source model’s option list is never consulted. Measured on 2.4.8-p5:

SentResponseStored
"status": 02000
"status": 72007
"visibility": 9920099
country_of_manufacture = "ZZZ"200ZZZ

No option validation on this route at all, for select attributes or for anything else. That is worth knowing beyond status, but status is where it does damage, because of what website scope does with it next.

The whole failure fits in one sequence. Three ordinary requests, each answered 200, leave a product that reads as enabled at default scope and is invisible to every customer on the website. The fourth request is the only one that repairs it:

sequenceDiagram
    autonumber
    participant E as ERP feed
    participant M as REST API
    participant D as catalog_product_entity_int

    E->>M: PUT /rest/all/ · status 1
    M->>D: store 0 = 1
    Note over D: enabled on every website

    Note over E: active=false is cast to 0,<br/>not mapped to 2
    E->>M: PUT /rest/default/ · name "…DE" + status 0
    M->>D: store 1 = 0 · store 2 = 0 · store 3 = 0
    M-->>E: 200 OK
    Note over D: website scope fans one scoped<br/>write across the whole website

    Note over E,D: product goes dark — 0 and 2 are indistinguishable here,<br/>so the disable half passes acceptance

    E->>M: PUT /rest/all/ · status 1
    M->>D: store 0 = 1
    M-->>E: 200 OK · "status": 1
    Note over D: store rows are still 0, and they win

    Note over E,D: activation succeeds and changes nothing, indefinitely.<br/>The grid cell is blank, not "Disabled", because 0 matches no option

    E->>M: PUT /rest/default/ · status null
    M->>D: store 1, 2, 3 deleted
    Note over D: override gone, website inherits again

The rest of this section is each step of that, measured.

The fan-out

status is is_global = 2 — website scope. A store-view-scoped write does not write the store view in the URL; it writes every store view of that store view’s website. On a sandbox where Main Website (1) holds store views 1, 2 and 3 and a Second Website (3) holds store view 5:

PUT /rest/all/V1/products/SKU          {"product":{"sku":"SKU","status":1}}
  catalog_product_entity_int → store 0: 1

PUT /rest/default/V1/products/SKU      {"product":{"sku":"SKU","status":0}}
  catalog_product_entity_int → store 0: 1 | store 1: 0 | store 2: 0 | store 3: 0

One request against one store view wrote three override rows. That part is correct behaviour for a website-scoped attribute and would be equally true of a legitimate 2.

Website-level activation is now dead

The value 0 is not 1, so nothing on Main Website treats the product as enabled. The natural fix is to enable it at default scope — and it does nothing:

PUT /rest/all/V1/products/SKU          {"product":{"sku":"SKU","status":1}}
  catalog_product_entity_int → store 0: 1 | store 1: 0 | store 2: 0 | store 3: 0
Read routestatus
/rest/all/1
/rest/default/0
/rest/zurich_view/0
/rest/amsterdam_view/0
/rest/second_view/1

The default row says Enabled, every store view of the affected website says 0, and the second website — which the write never touched — is unaffected. An integration that flips a product back to active at global scope reports success on every run and changes nothing that a customer can see.

Storefront-side, 0 and 2 are indistinguishable. After a catalog_product_price reindex the product held four index rows for website 3 and none for website 1, identically for status: 0 and status: 2 — the price indexer’s status join is = STATUS_ENABLED, and neither value is 1.

Why nobody finds it in the admin

Because 0 is not an option, Status::getOptionText(0) returns null. The product grid’s status column is a Magento_Ui/js/grid/columns/select, whose getLabel() collects labels for options that match and joins them — an unmatched value produces an empty string. The column renders blank. Not "Disabled", not 0. There is nothing to notice.

And the state cannot be produced from the admin at all. status is frontend_input = select with that source model behind it, so the form and the mass action can only ever offer 1 or 2. This is a REST-only condition, which is exactly why there is no folk knowledge about it: the people who would normally recognise a scope override from the Use Default Value checkbox have never seen a product get into this shape.

Clearing it

A store-scoped override is removed by deleting the row, not by writing over it, and the API does expose that — send null:

PUT /rest/default/V1/products/SKU      {"product":{"sku":"SKU","status":null}}
  catalog_product_entity_int → store 0: 1

The three store rows are gone and the website inherits the default again. This is the use_default reset described in the verification record below, reached from the API rather than from the form, and the distinction between null and empty matters: on a store-scoped meta_title, "value": null deleted the row while "value": "" wrote a row holding SQL NULL — which pins "no value" at that scope instead of restoring inheritance. Sending an empty string is not a reset; it is a different override.

One trap on the way out, and status is unusually exposed to it. null through /rest/all/ targets the store_id = 0 row, and for a required attribute the platform stops you: {"name": null} at default scope returns 400 The "Product Name" attribute value is empty. status is is_required = 0, so it gets no such guard. {"status": null} through /rest/all/ returns 200 and leaves the product with no status row anywhere. GET then reports "status": 1, because eav_attribute.default_value for status is 1 — but _addAttributeToSelect() in the price indexer joins the store_id = 0 row with an inner join when a condition is present, so the product is dropped from catalog_product_index_price entirely. Reproduced: rows deleted, reindex, zero index rows, while REST still answered 1. Any later product save writes the default row back and hides the evidence. Send null only through a store-view route.

What to do in the client

  • Map, never cast. $active ? 1 : 2. An (int) cast of a boolean is the bug.
  • Validate against the option list before sending. For status that is two values; the same check belongs on every select attribute, because the API will not do it for you.
  • Reconcile with SQL, not with a read. SELECT store_id, value FROM catalog_product_entity_int WHERE attribute_id = <status> AND value NOT IN (1,2) finds every product already in this state. A GET at default scope will not.

Product links are replaced wholesale — across every type at once

product_links carries related, up-sell and cross-sell products in one flat array, and its semantics are the opposite of category_links. Measured on one product:

SentResulting links
two related links (2, 3)related → 2, 3
one related link (2)related → 2 — the other one is removed
one upsell link (4), no related at allupsell → 4 only. Both related links are gone
a save omitting product_links entirelyunchanged

That third row is the trap. The array is not scoped to the link types it contains — it replaces the product’s entire link set. A feed that owns up-sells and knows nothing about related products will silently delete the related products a merchandiser set by hand, every single run, and report success.

So: omitting the key is safe, sending it is total. If the ERP owns only one link type, read the current product_links, keep everything of the types it does not own, and write the union back. This is the same shape as the category advice, arrived at from the opposite direction — there, a partial array under-deletes; here, it over-deletes.

Product types: what the minimum payload buys you

The same four-field payload plus type_id was accepted for five of the six built-in types:

type_idResult with a minimal payload
simple, virtual, downloadableCreated, price retained
groupedCreated, and price is dropped — a grouped product has no price of its own
configurableCreated, price coerced to 0 — the children carry price
bundle400 — The "Price View" attribute value is empty. Needs extension_attributes.bundle_product_options and a price view

Only bundle refuses. The other two surprises are silent: send a price with a grouped or configurable product and it disappears without comment, which looks like data loss if you are diffing what you sent against what you read back.

Reading products back: reproducing a category listing

Integrations read as well as write, and the first read anyone attempts is "give me the products in this category, the way the shop shows them". It is a good worked example because all three ways of getting it wrong are silent.

Measured on 2.4.8-p5 against sample data’s New Luma Yoga Collection (category 8):

Querytotal_count
Filter on category_id alone347
…plus visibility in 2,432
…plus status = 132

347 against 32. The naive query returns more than ten times what the storefront shows, and nothing signals it.

Issue 1 — visibility

Variant children are Not Visible Individually. They are genuine category members and the API is right to return them; they simply never appear on a listing page. Filter to visibility in 2,4 — Catalog and Catalog, Search — and add status = 1, remembering from the scope table above that status is website-scoped, so an "enabled" product may still be disabled for the website you are reading.

An in condition and two eq filters in the same group produce the identical count, since filters within one group are OR-ed. Use in; it is shorter and says what it means.

Issue 2 — the category link field is not the one you expect

Filter on category_id, singular. It works and returns exactly the row count in catalog_category_product.

category_ids — the plural field that appears in GET responses and is what most people try first — does not merely fail to filter. On 2.4.8-p5 it returns HTTP 500 with a report id and nothing useful in the response body. A hard failure rather than a silent one, but only if you notice it in a batch that otherwise succeeded.

Issue 3 — sort order cannot be expressed here

sortOrders on position is accepted and silently ignored. Verified by requesting the same category ASC and then DESC: byte-identical order both times. Position lives on the category-to-product relation, not on the product, so the product collection has nothing to sort by.

If you need the merchandised order, read the category side instead — GET /V1/categories/{id}/products returns {sku, position} per assignment. The practical pattern is to take the ordering from the category endpoint and the product data from the product endpoint, then join client-side.

That leaves one honest caveat: this reproduces a listing’s contents and order, not its behaviour. Layered navigation, price rules and stock-based exclusions are applied by the storefront on top, and none of them are visible to this query.

Filtering: what an integration needs to know

The full reference lives in Magento 2 searchCriteria: The Complete Reference for REST Queries — every condition type, the bracket syntax, and the silent failures. Compressed to what an integration actually leans on:

One rule covers AND and OR. Filters at different filter_groups indices are AND-ed; filters within the same group are OR-ed. That is the whole model, and it has a hard limit worth designing around: (A AND B) OR (C AND D) is not expressible. When a feed needs that shape, it needs two requests.

The condition types that carry an integration: eq / neq, in / nin for identifier sets, gt / lt / gteq / lteq for ranges, from / to for a bounded range — which must sit in separate groups, since two filters in one group would OR rather than AND — like / nlike with explicit %, finset for multi-select membership, and null / notnull.

Two more exist and are routinely omitted from third-party write-ups: nfinset, the negation of finset, and moreq, alongside the usual comparison family. Both are implemented in the query builder (Magento\Framework\DB\Adapter\Pdo\Mysql). Worth knowing before you write a client-side filter to compensate for one you assumed was missing.

Adobe documents one limit that catches integrations specifically: only top-level attributes are searchable. A field nested behind extension_attributes or custom_attributes cannot be filtered on directly, and the attempt surfaces as a storage-layer error naming a column rather than as a validation message — so it reads like a bug in your query rather than an unsupported operation.

Two integration-specific cautions on top of that reference:

  • Never page a searchCriteria read while writing to the same entities. Concurrent writes shift the result set between pages, so records are silently skipped or returned twice. Snapshot first, or sort on a stable key and page by that rather than by offset.
  • A store code in the route scopes attribute values, not the collection. Reading through a store route does not restrict results to that store’s website; if you need that, filter on it explicitly.

URL keys and rewrite bloat

The most common hard failure on import is URL key for specified store already exists. Sources:

  • Two SKUs whose ERP names normalize to the same slug.
  • A previously deleted product whose rewrite rows survived.
  • catalog/seo/save_rewrites_history enabled, so every name change adds a permanent 301 row.
  • Two products sharing one SKU, because a parallel importer created them both. This one is the section below, and it is the only source of the four that makes the SKU permanently unwritable.

On a large catalog with frequent name changes, url_rewrite grows into millions of rows and starts dominating save time. Decide deliberately whether history rewrites are worth it for import-driven changes; if not, disable the setting and prune. Always generate the url_key yourself from a stable field (SKU-derived, or name plus SKU suffix) rather than letting Magento derive it from a name the ERP will change.

Two concurrent creates, one SKU

catalog_product_entity.sku is not unique. It carries a plain btree index — <index referenceId="CATALOG_PRODUCT_ENTITY_SKU"> in Magento_Catalog‘s db_schema.xml, not a <constraint>. Uniqueness lives entirely in PHP: ProductRepository::save() runs an unlocked SELECT entity_id FROM catalog_product_entity WHERE sku = ? and treats an empty result as "create". Nothing underneath rejects the second row.

Two POST /V1/products calls carrying the same SKU that overlap inside that window therefore both succeed:

POST /V1/products  {"product":{"sku":"ERP-1001", ...}}   -> 200  {"id":2134, ...}
POST /V1/products  {"product":{"sku":"ERP-1001", ...}}   -> 200  {"id":2135, ...}

Two 200s, two different ids, one SKU. Fourteen races on 2.4.8-p5 — eight through the repository, six over REST — produced a duplicate row every time.

What happens next is decided by which of the two won the url_rewrite insert, because url_rewrite (request_path, store_id) is a real unique constraint:

  • The higher entity_id won it. Ten of the fourteen. Every later write for that SKU now fails, permanently. A SKU resolves to the lowest entity_id — getIdBySku() takes the first row it finds — and that row can never claim a request_path the other one holds. PUT /V1/products/ERP-1001 returns 400 {"message":"URL key for specified store already exists."} on the first retry and on every retry after it.
  • The lower one won it. The other four. Writes keep succeeding and nothing surfaces at all. What you have is an orphan product on a live SKU: unreachable through every SKU-addressed route, uncounted by any reconciliation that groups by SKU, and visible to a customer only if it later acquires a URL of its own.

That is what makes the error message so misleading. URL key for specified store already exists reads like a slug collision — the three causes above, all of them about names. When it turns up on a SKU whose name has never changed, look for the duplicate first:

SELECT sku, COUNT(*) c, GROUP_CONCAT(entity_id)
FROM catalog_product_entity GROUP BY sku HAVING c > 1;

Recovery is one call, with a trap in it. ProductRepositoryInterface::deleteById() takes a SKU, not an entity id, so DELETE /V1/products/{sku} always removes the lowest duplicate — which is the only one a SKU-addressed route can reach at all. In the broken case that is exactly the row you want gone: afterwards the SKU resolves to the product that owns the URL, and writes work again. In the silent case the same call deletes the live product and promotes the orphan. Check which entity owns the rewrite before firing it.

The constraint is not coming. magento/magento2#31125 has been open and confirmed since December 2020, still reproducible on 2.4-develop when Adobe re-verified it in July 2024. The obvious fix cannot ship: on Adobe Commerce, Content Staging replaces the table’s primary key with row_id and legitimately stores several rows per SKU, scoped by created_in / updated_in. PR #33191 tried adding the unique key anyway; that objection was raised on it, never answered, and the PR was closed unmerged sixteen months later. Open Source could carry the constraint alone, but the schema is shared, so nobody has.

What can ship on both editions is a lock around the get-or-create window, and magento/magento2#41181 proposes exactly that: a per-SKU named lock held across ProductRepository::save(), using the LockManagerInterface that already exists in the framework and that the repository does not currently touch. No schema change, backward compatible, correct under Content Staging. Whether it lands is Adobe’s call.

Until something does, prevention is the importer’s job — or a module. BroCode_UniqueSku packages both layers, the schema change and the lock, for installing today. Measured on 2.4.8-p5 with two parallel POST /V1/products carrying one SKU:

InstalledResult
stock Magento200 + 200, two rows
the constraint alone200 + 400 Unique constraint violation found, one row
constraint and lock200 + 200 with the same id, one row — the second call is an update

Read its compatibility note before installing: the schema half must not go onto Adobe Commerce with Content Staging, for the reason above, and setup:upgrade will refuse to apply it at all if the catalog already contains duplicates.

Which means, module or not:

  • Partition the feed by SKU, not round-robin. Hash the SKU to a worker so one SKU is only ever held by one process. Round-robin over a feed that mentions a SKU twice is the exact reproduction above.
  • A retry is a second writer. A timeout that leaves the first call running and fires a retry produces the same overlap, from a single-threaded importer. Make creates idempotent by checking GET /V1/products/{sku} first, and treat a timeout as unknown, not as failed.
  • async/bulk does not save you. It is the same repository behind several consumers; #30893 reports duplicates from /async/bulk/V1/products specifically. Not re-tested here.
  • Reconcile after every full import with the GROUP BY above. It is three seconds of SQL and it is the only thing that catches the silent half.

Working example: a delta sync that behaves

Shape, not framework. Four phases, each using the narrowest endpoint that does the job.

1. Authenticate once, cache the token.

TOKEN=$(cat /var/run/mage-token 2>/dev/null)
if [ -z "$TOKEN" ]; then
  TOKEN=$(curl -s -X POST "$BASE/rest/V1/integration/admin/token" \
    -H 'Content-Type: application/json' \
    -d '{"username":"'$API_USER'","password":"'$API_PASS'"}' | tr -d '"')
  echo "$TOKEN" > /var/run/mage-token
fi

For production, use an Integration token from the admin instead and skip this entirely.

2. Structural changes — bulk, global scope, no media, no stock, no price.

curl -s -X POST "$BASE/rest/all/async/bulk/V1/products" \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '[
    {"product":{"sku":"ERP-1001","name":"Kettle 1.7L","attribute_set_id":4,
      "type_id":"simple","visibility":4,"status":1,
      "extension_attributes":{"website_ids":[1]},
      "custom_attributes":[
        {"attribute_code":"url_key","value":"kettle-1-7l-erp-1001"},
        {"attribute_code":"manufacturer","value":"142"}
      ]}},
    {"product":{"sku":"ERP-1002","name":"Kettle 2.0L","attribute_set_id":4,
      "type_id":"simple","visibility":4,"status":1,
      "extension_attributes":{"website_ids":[1]}}}
  ]' | jq -r '.bulk_uuid'

Note: url_key derived from SKU, manufacturer sent as an option ID, website_ids explicit, no media_gallery_entries, no stock_item.

3. Poll the bulk until it is actually done.

UUID=$1
DEADLINE=$(( $(date -u +%s) + 1800 ))   # give up after 30 minutes
while :; do
  STATUS=$(curl -s "$BASE/rest/V1/bulk/$UUID/status" \
    -H "Authorization: Bearer $TOKEN")
  FAILED=$(echo "$STATUS" | jq '[.operations_list[] | select(.status > 1)] | length')
  OPEN=$(echo "$STATUS" | jq '[.operations_list[] | select(.status == 4)] | length')
  [ "$OPEN" -eq 0 ] && break
  if [ "$(date -u +%s)" -ge "$DEADLINE" ]; then
    echo "bulk $UUID still has $OPEN open operations - consumer stalled?" >&2
    exit 1
  fi
  sleep 5
done
[ "$FAILED" -gt 0 ] && echo "$STATUS" | jq '.operations_list[] | select(.status > 1)' >&2

Do not fire and forget. A bulk with failed operations that nobody reads is worse than a synchronous import that crashes loudly.

The deadline is not defensive padding. An operation only leaves status 4 when a consumer claims it, and the cron that sweeps incomplete operations filters on a start timestamp that unclaimed rows never get — so a bulk queued while async.operations.all was down stays open forever and a loop without a deadline waits with it. Also check the credential can read that status route at all: it is guarded by an action-log resource unrelated to catalog, so a properly scoped integration account is refused. Both in Magento Async Bulk API: What the 202 Doesn’t Tell You.

4. Deltas — prices and stock — through the narrow endpoints. Covered in Prices and Stock via REST; they are synchronous, array-shaped, and must not be a product save.

5. Media, separately and conditionally.

EXISTING=$(curl -s "$BASE/rest/V1/products/ERP-1001/media" -H "Authorization: Bearer $TOKEN")
echo "$EXISTING" | jq -e --arg h "$ASSET_HASH" '.[] | select(.label == $h)' >/dev/null \
  || curl -s -X POST "$BASE/rest/all/V1/products/ERP-1001/media" \
       -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
       -d '{"entry":{"media_type":"image","label":"'$ASSET_HASH'","position":1,
            "disabled":false,"types":["image","small_image","thumbnail"],
            "content":{"base64_encoded_data":"'$B64'","type":"image/jpeg",
                       "name":"erp-1001.jpg"}}}'

What to skip

  • Don’t rebuild bin/magento import over REST. For a genuine full-catalog load, the CSV importer is still an order of magnitude faster because it bypasses the repository layer. REST is for deltas and for systems that cannot drop a file on the server.
  • Don’t GET-before-PUT for every SKU. Two requests per product to avoid an unnecessary write is a bad trade. Hash the payload on your side and skip rows whose hash is unchanged since the last successful run.
  • Don’t use plain /async without /bulk. You get queueing without batching — all of the deferred-error downside, none of the request-count upside.
  • Don’t chase atomicity. There is no cross-resource transaction. Idempotency and a resumable progress log are the achievable goal.
  • Don’t page a searchCriteria read while writing. Concurrent writes shift the result set between pages and you will silently skip or duplicate records. Read into a snapshot before the import, or filter on a stable sort key — see Magento 2 searchCriteria: Complete REST Reference.
  • Don’t retry validation errors. A 400 from an EAV validator will fail identically forever. Retry 40001, 429, 502/503/504. Everything else goes to a dead-letter file for a human.

Verification

Before declaring an import correct. The SQL here is diagnostic only — see the note at the top of this document; run it from a console to find out what happened, never from the integration.

# indexers are scheduled, not on-save, and none are invalid
bin/magento indexer:status

# the async consumer is alive
ps aux | grep async.operations.all
bin/magento queue:consumers:list | grep async

# failed bulk operations (status > 1 means not complete)
-- bulk operations that did not complete
SELECT bulk_uuid, status, COUNT(*)
FROM magento_operation GROUP BY bulk_uuid, status;

-- accidental store-scope overrides on attributes that should be global
SELECT a.attribute_code, v.store_id, COUNT(*)
FROM catalog_product_entity_varchar v
JOIN eav_attribute a ON a.attribute_id = v.attribute_id
WHERE v.store_id <> 0
GROUP BY a.attribute_code, v.store_id
ORDER BY 3 DESC;

-- url_rewrite growth
SELECT entity_type, COUNT(*) FROM url_rewrite GROUP BY entity_type;

-- duplicate SKUs left behind by a parallel importer
SELECT sku, COUNT(*) c, GROUP_CONCAT(entity_id)
FROM catalog_product_entity GROUP BY sku HAVING c > 1;

Then the storefront checks that no query answers: pick five imported SKUs, confirm they are visible in the correct websites, priced correctly per store view, salable with the expected quantity, and that the configurable parents actually add to cart.

A catalog sync is correct when re-running it twice in a row changes nothing — no new media files, no new rewrite rows, no new _cl entries beyond the run itself. If the second run is not a no-op, the first one was not idempotent.


Verification record

Verified 2026-08-25 (two passes) against a magento2-sandbox install: Magento Open Source 2.4.8-p5, Luma + sample data, production mode, MySQL message queue, no RabbitMQ, no Commerce staging. Claims were executed, not reasoned about — REST calls against the running store, SQL against its database, and source read only to explain a result already observed. Probe products, attributes, options and media were removed afterwards.

Findings from the same passes that belong to the split-out articles live there, each with its own record: Media, Prices and Stock, Categories and Attributes.

Corrected — this document said the opposite before the verification passes:

Claim as writtenWhat 2.4.8-p5 does
async/bulk requires RabbitMQWorks on the DB queue. async.operations.all declares no connection, and DefaultValueProvider returns db unless queue/amqp is set. 202 → status 4 → drained to status 1 → products created, no broker installed

Confirmed as written: the scope-fallback asymmetry (/rest/all/ → store_id 0; scopeless PUT → a second row at store_id 1), and its async/bulk equivalent — magento/magento2#23142 is fixed, /rest/{store}/async/bulk/ lands on that store while the scopeless async route creates the same default-store override; oauth/access_token_lifetime/admin = 4 hours; operation status constants 1 complete, 2/3 failed, 4 open, 5 rejected; catalog/seo/save_rewrites_history defaulting to 1; and every REST route and bin/magento command named here.

Established by testing:

  • Configurables fail silently in the two places it matters. A parent created with options but no children returns 200 and leaves children: [] — the unbuyable PDP, no exception. A numeric-but-nonexistent value_index also returns 200 and creates the option with "values": []. A label where an option id belongs does fail loudly (400, type error), and POST .../child is not idempotent — relinking returns 400 "The product is already attached."
  • The use_default reset has no dedicated method, but it does have a payload. AttributeFilter::prepareDefaultData() sets varchar/text/datetime attributes to boolean false (numerics to null) and AbstractEntity::_processSaveData() turns that into a row DELETE. Reproduced: the store-2 row vanished and the product resolved the global value again. Amended 2026-09-07 — a plain null on a scoped route reaches the same DELETE over REST, on required and optional attributes alike; the is_required guard applies at default scope, where it rejects the save rather than emptying the default row. The scope section above has the measurements and the one place that guard is missing.
  • Unresolved message placeholders are a general pattern across this API. The configurable link error is The child product doesn't have the "%1" attribute value. with the attribute name only in parameters. Read parameters; never log message alone.

Attempted and not reproduced: deadlocks under parallel writers. 256 concurrent overlapping saves returned 256 × 200 with no 40001 and a clean exception log. The sandbox is too small for this to mean anything beyond "not reproduced here" — see the honest note in that section. The second pass at concurrency, below, found the failure that pass was looking in the wrong place for: parallel writers do not deadlock, they duplicate.

Added 2026-08-31, same sandbox. "Two concurrent creates, one SKU" was executed rather than reasoned about. Fourteen races — eight driving ProductRepositoryInterface::save() from two CLI processes off a shared wall-clock barrier, six firing two parallel POST /V1/products with a real admin token — produced two catalog_product_entity rows on one SKU every time, all twenty-eight calls returning 200. Ten of the fourteen left the SKU permanently unwritable: PUT /V1/products/{sku} answered 400 URL key for specified store already exists. on every subsequent attempt. The remaining four left a silent orphan. Which of the two happens is decided by whether the higher or lower entity_id won the url_rewrite insert. DELETE /V1/products/{sku} was confirmed to remove the lowest duplicate and to restore writes in the broken case. The schema facts behind it — CATALOG_PRODUCT_ENTITY_SKU non-unique, URL_REWRITE_REQUEST_PATH_STORE_ID unique — were read off information_schema on the running install, not off the db_schema.xml.

Added 2026-09-01. The fix was built and measured rather than described. The schema change from magento/magento2#33191 applies cleanly from a third-party module on 2.4.8-p5 — CATALOG_PRODUCT_ENTITY_SKU becomes NON_UNIQUE = 0, and module:disable plus setup:upgrade reverts it — so the 1061 Duplicate key name that stalled that PR in 2021 no longer reproduces here. With the constraint alone the race yields one row and a 400 for the loser; with the per-SKU lock added, both callers get 200 with the same id and one row, five races out of five. Both results are on the same sandbox, which was returned to its stock schema afterwards.

Added 2026-09-07, same sandbox. The status: 0 section was executed end to end on a two-website install (Main Website with store views default, zurich_view, amsterdam_view; a Second Website with second_view). status: 0, status: 7, visibility: 99 and a country_of_manufacture of ZZZ were all accepted with 200 and persisted, confirming that this route validates no select attribute against its source model. catalog_eav_attribute.is_global = 2 for status was read off the running database, and a store-scoped PUT was observed writing rows for all three store views of that website. A subsequent status: 1 through /rest/all/ left those rows untouched, and per-store GETs returned 1 / 0 / 0 / 0 / 1. A catalog_product_price reindex left four index rows on the untouched website and none on the affected one, identically for 0 and for 2. Status::getOptionText(0) returning null and select.js getLabel() joining only matched options were read to explain the blank grid cell, after the null was observed. The reset path was measured both ways: status: null on a store-view route deleted the three rows; status: null on /rest/all/ deleted the store_id = 0 row as well, after which GET reported "status": 1 from eav_attribute.default_value while a reindex produced zero catalog_product_index_price rows. On a store-scoped meta_title, "value": null deleted the row and "value": "" wrote one holding SQL NULL — the two are not interchangeable. The required-attribute asymmetry was measured on name (is_required = 1): null at store-view scope returned 200 and removed the override, null at default scope returned 400 The "Product Name" attribute value is empty. status is is_required = 0 and got no such guard. Probe products were removed afterwards.

Still untested: every 2.4.9 claim in "Why this matters now", which needs a 2.4.9 install rather than this 2.4.8-p5 one.

The pattern worth carrying forward: the wrong claims here were not wrong identifiers, they were wrong mechanisms — plausible sentences about how a subsystem behaves, several of which were true years ago and quietly stopped being true. Those are the ones that survive review, because nothing about them looks like a typo.

Related Topics

← Previous
Next →

Written in collaboration with AI (Claude, by Anthropic). Ideas, verification, and accountability are mine; research and drafting are AI-assisted. Full disclosure → · Found an error? Tell me.