Allegro

@zanreal/medusa-allegro

Medusa v2 plugin for Allegro, the largest marketplace in Poland.

Full documentation, in English and Polish, is published at https://zanreal.com/docs/oss/medusa-allegro and authored in docs/.

Status: pre-release. The full sync engine is here: offer discovery, a read-only pricing monitor, price-automation writes, the quantity push, and the order event drain. Treat the schema as settled and the API surface as still moving until 1.0.

What is here:

• A zero-dependency, fetch-based Allegro REST client, ported from a production integration. Offers, promo options, price-automation rules and commands, order events, checkout forms, categories, fee preview.
• OAuth 2.0 authorization-code flow with a CSRF-protected callback, refresh-token rotation, and AES-256-GCM encryption of both tokens at rest.
• Offer discovery matches every seller offer's sygnatura to a Medusa variant SKU, sweeps promotion state in one paginated pass, creates category rate rows, and records conflicts instead of guessing.
• A read-only pricing monitor records each offer's price mode, attached rule and drift, and audits real rule transitions.
• Price sync attaches the rule the promotion state calls for and asserts [break-even, SRP] bounds, with a per-run change cap, per-offer quarantine, a circuit breaker, and write-scope detection.
• Stock push reconciles Medusa's available quantity into Allegro through the quantity-change command.
• Order sync drains GET /order/events into Medusa orders, with fulfillment write-back and an operator import window for gaps beyond the event retention period.
• Invoice attach puts an issued invoice PDF onto the Allegro order, driven by an event from an invoicing module and retried by a bounded sweep. A soft dependency in one direction only - see The invoice chain.
• Admin surfaces built around one rule - per-product state on the product, everything else under Settings. A product detail widget shows each variant SKU's linked offer, status, drift, promotion state and per-offer price sync opt-out (with a push-history drawer); a compact product-list banner rolls up linked / drifting / conflicting counts; the connection, writer toggles, category rates, the cross-catalogue offers table and the orders task-flow all live under Settings -> Allegro, with nothing Allegro-specific in the main ecommerce sidebar. See Admin UI.

Nothing writes to Allegro until you arm it. Every writer is governed by a persisted, admin-flippable toggle that ships off on a fresh install, so a newly connected store publishes nothing until an operator arms each writer under Settings -> Allegro - no redeploy needed to arm or disarm, and the environment can still hard force-disable any writer regardless. On top of that: price sync is inert without automationRules, and a fresh install starts its order cursor at "now" rather than importing history. See Runtime toggles and Turning the writers on.

Install

@zanreal/medusa-allegro is on npm:

That resolves to a prebuilt tarball - the published package already contains the .medusa/server output its exports point at, so nothing needs to compile on install. It pulls @zanreal/medusa-admin-kit from the registry too, for the Catalog columns it contributes.

main keeps moving after a release ships (see Releasing), so if you need a fix or feature that has landed on main but not yet been released, install it as a git dependency instead, pinned to a commit:

Pin the commit you tested against. #main would move under you on the next push.

Installed that way, the package compiles itself on install - prepare runs medusa plugin:build, which turns the checked-out source into the .medusa/server output its exports point at. pnpm 10 and newer refuse to run that script for a dependency they do not already trust, so a fresh install needs it allowed once in your own project:

The key is the exact tarball URL pnpm resolves the pinned commit to, which is why it carries the same SHA as the dependency line - move both together.

Register it in medusa-config.ts:

Then run the migrations:

npx medusa db:migrate

Options

Sync options

All options are validated in a module loader, so a misconfiguration fails at boot with a specific message instead of surfacing as an opaque Allegro error later. The validations worth knowing about, because each catches a mistake that would otherwise present as a silently inert loop:

• A boolean-looking string on any kill switch throws. priceSyncDisabled: process.env.X yields "true", which a truthiness test honours and a === true test ignores - the switch would read as enabled while you believed it was off.
• One rule name used for both promotion states throws. A promotion flip would then be a no-op switch, so the promoted commission rate would never reach the price floor, and price sync would look healthy while systematically under-flooring every promoted offer.
• Both SRP sources set at once throws. The ceiling is what stops an automation rule ratcheting a price down; two sources means an ambiguous ceiling.

Environment variables

The schedules and force-disable overrides are env vars rather than plugin options because Medusa evaluates a scheduled job's schedule at plugin-load time, before the DI container - and therefore this plugin's options - exists. There is no way to read a module's resolved options from that static export.

The schedules start firing as soon as the plugin loads, but the writers are armed by the persisted toggles, which ship off. Installing or upgrading this plugin runs the loops on their cadence, but every writer stays disarmed until you arm it under Settings -> Allegro (or the environment force-disable, if set, keeps it off regardless). The read paths are harmless (discovery and the monitor write nothing to Allegro). If you are staging a cutover from another system and want belt-and-braces, set the force-disable env vars BEFORE the version that reads them ships. See Runtime toggles and Turning the writers on.

Pricing modes

How this store prices its Allegro offers is a setting, not an assumption. Pick one of three modes under Settings -> Allegro; it takes effect on the next sync run, with nothing to restart.

automation_rule is the default, because it is what this plugin did before the mode existed. Upgrading changes nothing about what your store writes.

The floor and the ceiling apply in every mode

The break-even floor (from @zanreal/medusa-product-costs, grossed for VAT and for the category commission) and the SRP ceiling (from variant metadata or a price list) are the safety story of this whole plugin, so no mode is allowed to skip them:

• monitor computes both and reports how many offers are priced outside them. That report is what you read before choosing a mode that writes.
• automation_rule sends them as the rule's price range, so Allegro's engine cannot move the price outside them.
• fixed_price checks the Medusa price against them and refuses to push a price below the floor or above the ceiling, counting it as price-outside-bounds.

A refusal is deliberate, and it is not a clamp. Clamping would sell at a price the store never set; pushing would sell below cost. Refusing does neither, and it names the variants whose Medusa price needs fixing.

What fixed-price mode needs, and what it does about it

Two things are true and worth stating plainly before you switch a live store to it:

• The scope is already there. PUT /sale/offer-price-change-commands/{commandId} needs allegro:api:sale:offers:write, which is in this plugin's default scope string and is the same scope the rule assignment already uses. Moving to fixed-price mode needs no reconnect and no new consent.
• An automation rule beats a fixed price, so the rule has to go first. Allegro's engine recalculates an offer on its own schedule, so a price pushed under a live rule does not survive it. Fixed-price mode therefore issues POST /sale/offer-price-automation-commands with a remove modification for the offer's marketplace, waits for it to confirm, and only then sets the price. If the removal does not confirm, the price is not sent at all - a half-applied pair that left the rule attached and the price changed is precisely the fight with Allegro's engine the sequencing exists to avoid. Re-running the pair next tick is idempotent.

Both commands count as one offer against the per-run change cap.

Where the fixed price comes from

The variant's own default price in Medusa, in the offer's own currency. Two rules, both fail-closed:

• Price-list rows are ignored. A price carrying a price_list_id is a sale or a customer-group override with its own validity window and conditions, none of which this plugin evaluates. Pushing one would leave a sale price on Allegro long after the sale ended.
• There is no currency conversion. A variant with no price in the offer's currency is skipped as missing-medusa-price rather than priced from a rate this plugin cannot audit.

Auditing

Every mode writes to the same append-only allegro_price_push trail, but they fill different columns, and the difference is load-bearing:

• automation-rule rows carry bound_floor / bound_ceiling and the rule ids. Those two columns are the only memory of the price range attached to a rule, because Allegro accepts a range and never returns one.
• fixed-price rows carry price_amount / price_currency and leave the bounds columns null, plus rule_id_old / rule_name_old for the rule that was removed. Writing the guard rails into the bounds columns would make a later automation-rule run read back a price range that was never attached, and skip an offer it should have re-attached.

Monitor mode and the price-write toggle

Monitor mode runs even while the Price writes toggle is off, because it has no command path to reach - exactly like the read-only price-automation monitor, which has never had a kill switch. The two writing modes honour the toggle as they always have, re-reading it before every single command. An explicit per-offer push from a product page is refused in monitor mode rather than quietly performed.

Runtime toggles

Every writer that reaches Allegro is governed by a persisted, operator-flippable toggle, stored as a one-row allegro_settings singleton. This is the live arming an operator controls from Settings -> Allegro - flip a switch and it takes effect on the next tick or event, with no redeploy, because every runtime path resolves its effective state from the persisted row at the top of each run rather than from a value captured at boot.

The five governed writers:

Precedence

The environment (and the boot-time plugin option) is a hard override that can only force a writer OFF. It never arms one. The effective state is:

effectiveEnabled = persistedEnabled && !forceDisabled

So:

• persisted on + env unset -> on (the writer runs)
• persisted on + env force-disable -> off (the override wins; an operator responding to an incident is not undone by a stale armed toggle)
• persisted off + env unset -> off (nothing arms a writer but the toggle)

The admin shows a switch that the environment forces off as locked and "forced off by environment", with the env var to clear - it never renders an armed-looking switch for a writer the environment is holding down. A write to a forced-off toggle is still accepted and stored, so the intent is preserved for when the override is lifted.

Fresh-install defaults

Every writer ships off, so a freshly connected store publishes nothing to Allegro until an operator arms each writer deliberately. Invoice attach is the one exception - it ships on but inert: by the time an invoice event reaches this plugin the document already exists as a legal record, so delivering it is the safe default, and there is nothing to attach until an invoicing module is wired and emitting events.

The singleton row is created lazily under a fixed primary key on first read, with these defaults. Upgrading an existing install runs the additive migration that creates the table; the row appears the first time any runtime path or the admin reads it.

Sync configuration fields

Nine settings - the pricing mode, the two automation rule names, the SRP source, the change cap, the marketplace id and the sales-channel scope - are editable from Settings -> Allegro, on the same allegro_settings singleton the runtime toggles use. An edit persists and takes effect on the next sync run, no redeploy - the same property the toggles have. A store that never touches these admin fields behaves exactly as before: every persisted column starts null, and null falls through to the medusa-config.ts option.

Precedence

Adapted from the toggles' "the override can only force off" contract to a value rather than a boolean - there is no "off" for a string or a number, so a set environment lock wins outright:

effectiveValue = envLock ?? persistedValue ?? medusaConfigDefault

• an env lock, when set, is authoritative - it beats both a persisted admin edit AND the medusa-config.ts option, and the admin shows the field locked, the same treatment a forced-off toggle gets
• otherwise the persisted admin value governs, when one has been entered
• otherwise the medusa-config.ts option governs, exactly as it always did

Clearing a field in the admin (blank it and Save) writes null, which falls back to the medusa-config.ts option rather than to an empty value - the same "clear" contract the category-rates page already uses.

Marketplace id and sales channel id are wiring-critical

Editing marketplaceId or salesChannelId re-scopes which Medusa products this plugin matches against Allegro offers, not merely a tuning knob - a wrong value breaks the mapping silently rather than producing an obviously bad result. Both stay editable and persisted, with the same env-lock escape hatch as everything else: set ALLEGRO_MARKETPLACE_ID or ALLEGRO_SALES_CHANNEL_ID to pin the correct value against an admin mistake during a cutover. The admin renders an explicit warning on both inputs saying so.

Automation rule names and SRP source stay mutually consistent

Two invariants that already existed as boot-time checks in resolveAllegroOptions - the standard and promoted rule names must differ, and at most one SRP source may be set - are now also enforced on every admin write, because persisting a field independently of the other can newly create a collision the boot-time check never saw (one half configured, the other newly persisted to the same value). The write is rejected with a MedusaError rather than silently accepted.

OAuth setup

1. Register an application with Allegro

1. Sign in to apps.developer.allegro.pl with the seller account you want to connect (use apps.developer.allegro.pl.allegrosandbox.pl for sandbox).

2. Create a new application. Choose the type that has a web application with a redirect URI - the plugin uses the authorization-code grant, not the device flow.

3. Name it something stable and machine-safe, with no spaces: MyStoreAllegro. This exact string goes into the appName option, because Allegro requires every request to carry a User-Agent that identifies the registered app one-to-one. The plugin composes {appName}/{appVersion} (+{docsUrl}) and validates it at construction time, so a name with a space is rejected before any request is sent.

4. Set the redirect URI to your backend plus redirectPath:

   https://your-medusa-backend.example.com/admin/allegro/oauth/callback

   Allegro compares this byte for byte during the token exchange. A trailing slash difference is a failed connection.

5. Grant the app the scopes you configured: offer read, offer write, order read.

6. Copy the client id and secret into ALLEGRO_CLIENT_ID and ALLEGRO_CLIENT_SECRET.

2. Generate an encryption key

Put it in ALLEGRO_ENCRYPTION_KEY. The plugin refuses to boot unless the value is canonical base64 (standard or URL-safe) for exactly 32 bytes, rather than silently accepting a weak one. The check is deliberately strict about the encoding and not only the length, because Buffer.from(value, "base64") never throws: it drops every character outside the alphabet, so a length test alone accepts mangled input, and "A".repeat(43) decodes to a well-formed all-zero key. Both are rejected.

The key also signs the OAuth state (see below), so rotating it invalidates any connection flow that is mid-air as well as the stored tokens.

3. Connect from the admin

Open Settings -> Allegro in the Medusa Admin and click Connect Allegro. You land on Allegro's consent screen, approve, and come back to the settings page with the account login, granted scopes, and token expiry filled in.

The page distinguishes three unhealthy states from a working connection, because each needs a different response: a missing refresh token (reconnect before the access token expires), an unreadable token envelope (the encryptionKey no longer opens what is stored - restore the old key or reconnect), and price sync disabled. A row whose envelope will not open is reported as such rather than as a green "Connected", which would send you looking at Allegro instead of at your own configuration.

How the flow is protected

• GET /admin/allegro/oauth/start mints a state, parks it in an httpOnly SameSite=Lax cookie with a 10-minute lifetime, and returns the authorization URL for the admin to navigate to. Over https the cookie carries the __Host- prefix, so a sibling subdomain cannot shadow it; over plain http it does not, because a __Host- cookie without Secure is dropped and local development would break.
• The state is not an opaque nonce. It is v1.<issuedAt>.<nonce>.<mac>, where the MAC is HMAC-SHA256 over the mint time, the nonce and the admin user's actor_id, keyed by encryptionKey. The admin id itself is not in the value, because the value travels through Allegro's authorize URL and into browser history and access logs.
• GET /admin/allegro/oauth/callback requires that state to match the cookie, compared in constant time, and to verify against the actor completing the flow. The cookie proves same-browser; the signature proves same-server, same admin, and minted within the last ten minutes. A state planted in someone else's browser fails the second check.
• The state cookie is cleared only once the authorization code has actually been handed to Allegro - which is when the state is spent, so it stays single-use. Branches that run before the state is verified (?error=..., a missing code, a state mismatch) deliberately leave it alone, so a lured GET to the callback cannot destroy a flow the operator legitimately started in another tab.
• Both routes live under /admin, which Medusa authenticates by default. The callback keeps that default: Allegro's redirect back is a top-level GET navigation and Medusa's admin session cookie is SameSite=Lax, so the session survives the hop. Making it public would also remove the actor_id the signed state is verified against, so every flow would fail instead.

If your deployment authenticates the admin with a bearer token in local storage rather than a session cookie, the callback will 401, because the browser has no cookie to send on that navigation. Serve the admin and the backend on the same origin with session auth; do not make the callback public.

Disconnecting

POST /admin/allegro/disconnect revokes the refresh and access tokens at Allegro and then deletes the stored row. Revocation is best-effort - if Allegro is unreachable the local connection is still removed, because refusing to disconnect would leave an operator unable to remove access they asked to remove.

When revocation is skipped or fails, the response carries a warning and the settings page shows it. That matters here more than in most places: the stored rows are the only copy of the tokens, so after this call there is nothing left to revoke with, and the refresh token stays valid at Allegro until it expires unless you remove the application's access by hand in the developer panel.

Admin UI

The information architecture answers two things at once: you should not have to open a separate table to see a product's Allegro state, and nothing Allegro-specific belongs in the main ecommerce sidebar - it is an integration's configuration and operator tooling, not a merchandising surface, so every non-per-product view lives under Settings.

• Product detail widget (product.details.after) - the authoritative per-product view. For every variant SKU it shows the linked offer (with a link to the live listing), a short status (linked / not linked / conflict), the observed price mode and drift, promotion state, the last price and stock sync times, and the per-offer price sync opt-out switch. The push history - the only record of the bounds ever sent - opens in a drawer. This is where an operator checks or opts a single product out, without touching the catalogue table.

  It fetches its own variants, and must. The dashboard loads the product for this zone with PRODUCT_DETAIL_FIELDS = getLinkedFields("product", "*categories,*shipping_profile,-variants") (@medusajs/dashboard/src/routes/products/product-detail/constants.ts). That -variants is an explicit exclusion - the page fetches the variant table separately with useProductVariants - so data.variants handed to a product.details.* widget is undefined. This widget derived its SKU list from data.variants and returned null when that list was empty, which meant it rendered nothing, on every product, on every store. It now calls sdk.admin.product.listVariants(productId, { fields: "id,title,sku" }) itself and still prefers data.variants if a future dashboard version passes it.

• Product list banner (product.list.before) - a compact roll-up (N linked / N unlinked / N drifting / N conflicts) above the stock products table, each count linking into Settings -> Allegro offers filtered to those rows. Medusa 2.18 does not allow injecting a custom column into the core products data table, and it exposes no list-row widget zone, so on that page a roll-up is the only thing a plugin can offer. It stays as the zero-dependency fallback for a store that has not installed admin-kit.

• Catalog columns (src/admin/widgets/register-variant-columns.tsx) - two columns registered into @zanreal/medusa-admin-kit's Catalog route, which lists one variant per row.

  Allegro is the live offer price, from allegro_offer.price_amount with its price_currency. It is a separate column rather than a second line inside the status badge, because the whole point of showing it is comparing it with the shop price and the SRP the kit renders two columns to the left, and that comparison needs a figure in a money column lined up with those, not a number inside a coloured badge. Priority 9 puts it immediately before the status column, so the three prices sit together. A price on a paused or ended offer is muted: the figure is real, but nobody can buy at it, and rendering it like a live price would read as current. A SKU with no offer, or an offer with no price observed yet, renders a muted -; never 0, and never an error.

  Allegro status is the mapping state. The cell names what is wrong with that one SKU: the conflict code (duplicate-sku, no-offer, ...) in red, drift in orange, Allegro's own offer status in green when it is listed and healthy, unlinked in grey, and a muted "not listed" when the SKU has no mapping at all. This is the real per-row status the banner could only approximate, and it does not cost this plugin a competing products list of its own.

  Both columns share one request per page. loadData runs per row, so two columns over a 100-row page would be 200 single-SKU requests for the same table. src/admin/lib/offer-batch.ts coalesces every SKU asked for within a tick - React flushes all the cells' effects in one pass - into a single /admin/allegro/offers?skus=... call, de-duplicating the SKU the two columns both want. It deliberately keeps no cache across batches: a price is exactly the thing a sync changes underneath the operator, so a re-render has to be able to re-read it.

  price_amount is a decimal string (model.text(), Allegro's own value verbatim), not a Medusa BigNumber, and resolveVariantOfferPrice reads it as one - with Number rather than Number.parseFloat, so "365,31" is rejected instead of silently becoming 365. An unreadable amount is null, which renders as the dash; 0 is left meaning zero.

  It used to read "3 offers / 1 conflict", because an admin-kit row was a product and a product spans many SKUs - which told an operator that something was broken without telling them which SKU, the one thing they needed in order to act. Now a row is one variant with at most one offer. The registration moved from registerProductColumn to registerVariantColumn and the SKU roll-up in src/admin/lib is gone: summarizeOfferStatus / formatOfferStatus became resolveVariantOffer / formatVariantOffer / variantOfferColor. The status column's header also changed from Allegro to Allegro status, so that the price column can carry the plainer name next to Shop and SRP.

• Settings -> Allegro - the configuration and control home: the OAuth connection, the live writer toggles (interactive switches backed by the persisted runtime settings - arm or disarm each writer without a redeploy; a writer the environment forces off is shown locked), the sync configuration fields (editable inputs backed by the same singleton - see Sync configuration fields; a field an environment variable locks is shown locked, same treatment as a forced-off toggle), a catalogue roll-up, sync health, and links into the three nested Settings pages below.

• Settings -> Allegro -> Offers - the cross-catalogue offer table with conflict and drift filters, bulk rediscovery, and manual push. An operator triage surface for catalogue-wide "which offers are not syncing, and fix them" work - a genuine multi-item workflow the per-product widget cannot serve, and distinct from the browse case the admin-kit Catalog column covers.

• Settings -> Allegro -> Orders - the orders quarantine repair and import window. Operational task-flow, not a setting itself, but still nested here rather than in the main sidebar.

• Settings -> Allegro -> Category rates - the per-category sale commissions that set every price floor. Pure configuration, hand-maintained from Allegro's published fee table.

The sygnatura / SKU mapping principle

A Medusa variant and an Allegro offer are linked by SKU, and only by SKU.

Allegro lets a seller put their own identifier on every offer, in the field the API calls external.id and the seller panel calls sygnatura. This plugin's contract is that you put the Medusa variant SKU there. Offer discovery then matches external.id against variant SKUs, and allegro_offer.sku carries a unique constraint because it is the identity of the row.

allegro_offer.offer_id is a resolved cache, never the identity. Allegro offer ids are not stable across an item's life: re-listing an ended offer produces a new id, and one SKU legitimately moves between offers over time. A mapping keyed on the offer id turns every re-list into a silent orphan that stops receiving stock and price updates while still looking healthy. A mapping keyed on the SKU turns the same event into a row whose offer_id needs re-resolving, which the next discovery pass does on its own.

Practical consequence: fill in the sygnatura on every Allegro offer you want managed. An offer without one is invisible to this plugin by design. That is the correct default - it means a seller can keep offers outside Medusa's control simply by leaving the field empty.

Data model

Three of these carry non-obvious constraints worth knowing before you build on them.

allegro_price_push is append-only, and it is the only record of pushed price bounds. Allegro's API accepts a [min, max] price range when you attach a price-automation rule to an offer, and it will tell you afterwards which rule is attached - but it never returns the range. The bounds are write-only. So this table is the only place that can answer "what floor is this offer pinned to, and who set it". Never update or delete a row; correct a mistake by appending. Rows with result: "observed" record state the plugin saw without touching, which is what makes a read-only monitoring pass worth running.

allegro_category_rate is filled in by hand, on purpose. Allegro does publish a fee calculator (POST /pricing/offer-fee-preview, wrapped by the SDK as offerFeePreview), but in production it rejects the offer bodies you can build from a seller's own live offers, so sweeping a real catalogue returns errors rather than rates. Until that changes, an operator enters rates from the published fee table. Both rate columns are nullable so "unknown" stays distinguishable from "zero commission": a margin calculation that reads a missing rate as 0% quietly turns a loss-making price into an acceptable one.

allegro_order is separate from the Medusa order on purpose. A checkout form can exist without an order (creation failed, so the form stays visible with its error rather than vanishing), Allegro's status ladder is richer than Medusa's enum, and derived_status has to be the comparison basis for "did Allegro move?" - see Status mapping. Its two invoice columns follow the same write-last discipline: allegro_invoice_id is stamped when the document is registered and invoice_attached_at only once Allegro has the file, so a row reading attached carries a PDF the buyer can download - see The invoice chain.

The sync architecture

Five loops, each with its own row in allegro_sync_state, its own single-flight claim, and - for the ones that write - its own kill switch. They are independently observable and independently runnable from the admin.

Two things write to Allegro outside the loops, both on a Medusa event: the fulfillment write-back and the invoice attach. Neither is a loop because neither has reconcilable state to compare - see Fulfillment write-back and The invoice chain.

The first three are chained into one job rather than scheduled separately because they all need the same input - a complete listing of the seller's offers - and paging a full catalogue three times an hour is how a well-behaved integration earns a rate limit. The order matters: discovery establishes which offer owns which SKU and which mappings are conflicted, and price sync refuses to write to anything conflicted, so running price sync against a stale mapping is exactly the case where a command lands on the wrong offer.

Stock has its own cadence because stock moves on every order and an hour-stale marketplace quantity is how a sold-out item stays purchasable — and it also has an event-driven fast path on top, so a sale updates its own SKUs within seconds rather than waiting for the sweep. Orders runs on a ~20s interval because an unapplied BOUGHT event is an order nobody has been told about; an interval rather than a cron because Medusa's cron only resolves to the minute.

Reconciliation first, events almost never

Every loop except fulfillment write-back is a reconciliation: it reads the whole relevant state on each run and computes the difference. None of them depends on a Medusa event firing.

That is deliberate. Medusa's inventory events are not a reliable trigger (medusa#11691), and a design that depended on them would leave a permanently wrong marketplace quantity behind every missed event. With reconciliation, a missed event costs at most one cycle of staleness.

The one loop that is only event-driven is fulfillment write-back, and it is an exception for a structural reason rather than a convenient one: a fulfillment is a point-in-time act, not reconcilable state. There is no "current fulfillment status" in Medusa for a sweep to compare against Allegro's, so the event is the only signal there is.

Stock is the one place where events and reconciliation run together. Order and reservation lifecycle events mark the SKUs they touched dirty, and a debounced queue pushes just those offers within seconds; the 15-minute sweep still reads the whole catalogue and repairs anything the events missed. The events are a hint about what to re-read, never a source of quantity — the push reads Medusa's available quantity and Allegro's offer for itself — so the unreliability behind medusa#11691 cannot produce a wrong write, only a late one. And because the sweep is unchanged, a dropped event costs exactly what it cost before: the next cycle.

Medusa inventory is the source of truth for stock

The quantity pushed to Allegro is retrieveAvailableQuantity - stocked minus reserved, so units already promised to unfulfilled Medusa orders are not advertised again.

Keeping Medusa inventory honest is explicitly not this plugin's job. In this stack that belongs to a separate inventory plugin, which owns the supplier snapshot and the arming gate that refuses to propagate an untrustworthy one into Medusa inventory. That guard lives one layer up, where the supplier response is actually visible; a second one here would be a guess about data this plugin has no source for.

What this loop does refuse on is its own uncertainty, and the line is drawn at UNKNOWNS rather than at gaps. An ambiguous SKU match, or a quantity that could not be READ on either side, refuses the whole plan: a partial push in that state leaves some offers fresh and others stale with nothing recording which is which, so the next run cannot tell either.

A KNOWN, bounded exclusion does not refuse anything. Each is counted, reported in last_error, and leaves exactly one offer alone: an inactive offer, a variant that does not manage inventory (so Medusa has no quantity to publish - a digital product, say), an offer that contradicts its mapping row, a mapped offer absent from the listing, an offer whose own Allegro listing carried no usable stock.available, and an eligible variant no mapped offer claims. Treating "this variant has no inventory" as an unknown is what previously let a single digital product with an Allegro offer refuse the entire catalogue's stock sync indefinitely.

A configured stockLocationIds is validated against the locations that exist, and an unknown id aborts the run. Medusa reports zero available quantity for a location that does not exi