Magento Integration Skills: Flow and Pitfalls, Not Routes

Eleven agent skills for building an ERP, PIM or OMS integration against Magento 2 — the behaviour no schema declares, verified against a running 2.4.8-p5 store.

Every Magento install ships a complete, machine-readable description of its own REST API — 432 declared routes and 326 payload interfaces on a stock 2.4.8-p5 store — and none of it says what those routes do. Nothing declares that a scopeless update writes a store-level override, that one endpoint reports per-item failures while its neighbour rolls back the whole batch, or that several writes return 200 and store nothing at all. This is that missing layer: eleven agent skills for an integration against Magento 2, carrying flow and pitfalls in prose, with no routes, no payloads and no client code in them anywhere.

Typical impact: the defects that normally surface weeks into a project — a catalogue full of scoped overrides nobody asked for, parents that never come back in stock, orders missing from a poll — get designed out before the first batch runs, because the skill names them at the moment the decision is made.

Who it is for

  • Developers building an ERP, PIM or OMS feed against Magento 2, in any language, over any client.
  • Anyone driving Magento’s REST API from an agent, where the model will otherwise answer from years of forum posts that were true in 2.3 and quietly stopped being true.
  • Teams inheriting an integration that "works" and want the list of silent failure modes to audit it against.
  • Architects sequencing the work — which wave unblocks the designer, the content team and the search consultant, and which one blocks nobody.

Who should skip it

  • Anyone who needs the route list or the payload shape. That is deliberately absent — export it from your own install instead, where it is already correct and stays correct.
  • One-off data loads where Magento’s own CSV import is the better tool, which is most genuine full-catalogue loads.
  • Adobe Commerce-only surface: company accounts, customer segments, store credit and staging were not exercised.

The set

SkillWhat it carries
magento-integration-flowBuild order, access preconditions, the failure modes every family shares, throughput and deadlocks, what has no API at all. Start here
magento-integration-queryingFilter combination and the shape it cannot express, reads that silently do nothing, paging safely while writing
magento-integration-async-bulkThe queued write path: a receipt that carries no entity, validation split across two moments, the status routes and the unrelated permission that blocks them
magento-integration-catalog-structureScope fallback, partial-update semantics, variant sequencing, a business key with no unique constraint, rewrite bloat
magento-integration-attributesTypes, options, per-store labels, swatches, and why third-party attribute properties are unreachable
magento-integration-mediaUnbounded duplication, the global-gallery versus per-store-view-role split, deletion refusals
magento-integration-prices-stockThe narrow endpoints, two opposite error models, salable versus source quantity, the composite parent that never recovers
magento-integration-categoriesThe missing natural key, asymmetric assignment paths, removal, rewrite growth
magento-integration-customersAn unauthenticated create that also sends mail, mail that cannot be deferred, an address update that destroys the row
magento-integration-ordersThe change cursor that drops rows, state that only moves as a side effect, the item rows that must not be summed
magento-integration-fulfilmentWhich document routes validate and which persist anything, a silent over-ship clamp, payment behaviour per method

What makes it different from a route index

Three rules the set holds to, and they are the reason it survives an upgrade:

  • No concrete calls. Routes, field names and payload shapes are version- and install-specific. They rot on the first upgrade and give no signal that they have rotted. The install already knows them; the skill does not repeat them.
  • Behaviour only. That a success status is not proof of storage, that idempotency differs between adjacent endpoints, that two similar-looking families have opposite error models — none of it appears in any declaration, and all of it survives a field rename.
  • Executed, not read. Every behavioural claim was run against a live store and read back from storage. Several contradict widely repeated advice, usually because the advice aged rather than because it was ever wrong.

Typical scenario

A nightly feed is built the obvious way: one product save per SKU, media inline, prices in the same payload. It passes the pilot. Then the real export arrives and the sync takes nine hours, pub/media grows by a copy of every photograph per run, and half the catalogue carries store-view overrides nobody wrote deliberately.

Each of those is a named entry in the set — narrow endpoints for prices and stock, media on its own cadence with client-side deduplication, and the scope rule that decides where a write lands. Every one of them leads back to a decision made in the first hour of the project, which is the cheapest place to make it and the only place it is free.

Installation

The skills are plain markdown with frontmatter. Clone and symlink them into whichever agent home you use:

git clone https://github.com/brosenberger/magento-integration-skills.git
cd magento-integration-skills
bin/install-symlinks.sh              # -> ~/.claude/skills
bin/install-symlinks.sh ~/.cursor/skills

Per-folder symlinks, idempotent, and it never overwrites an entry that is already there — a local skill of the same name wins and is reported. Pull to update; the links follow.

Compatibility

Behaviour is pinned to Magento Open Source 2.4.8-p5 with sample data, one website and four store views, MySQL queue with no broker, plus Elasticsuite for the third-party checks. The customer pass added a second website; parts of the composite-stock work were re-checked on 2.4.9 and on 2.4-develop.

Nothing in the set is client- or language-specific, so it applies equally to a PHP consumer, a Node worker or an agent driving the API directly. Re-test after a major or minor upgrade: the bundle’s own documentation ranks which classes of claim age fastest, and defect-shaped behaviour ages first.

FAQ

Why no endpoints or payloads at all?

Because they are the part the install already answers correctly and the part that goes stale silently. Export your own schema and drive it as a tool; the skill stays useful across versions precisely because nothing in it is version-shaped.

Is this an MCP server?

No. It is a skill set — knowledge an agent loads when the task matches. Pair it with a collection generated from your own install if you want the concrete calling layer.

How do I know the claims are current?

Every one traces to something executed against a running install, and the repository documents what was measured, what was only read from source, and what was deliberately not tested — including the payment behaviour, which came from a stand-in gateway and does not generalise to a real provider.

What if my install disagrees?

The install wins, always. Where a claim here contradicts what a store actually does, that is a version boundary worth recording rather than a bug in your integration.

Related reading

Related Topics

Ask a module question or suggest improvements

Tell us your use case and the module context. Spam protection is handled by ALTCHA.




More Projects