Configuration and control

Configuration lives in three layers, and knowing which one wins is the difference between a switch you can flip in an incident and a redeploy.

  environment variable   ->  hard override, and for a writer it can only force OFF
  persisted admin value  ->  what an operator edits under Settings -> Allegro
  medusa-config.ts       ->  the default the plugin was installed with

Options

Five are required. Everything else has a default.

Sync options

Force-disable options

Each of these can only force a writer off. None of them arms anything.

What fails at boot, and why

Every option is validated in a module loader, so a misconfiguration fails at boot with a specific message instead of surfacing as an opaque Allegro error later. Three validations are 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 environment variables rather than plugin options for a structural reason: 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 runs the loops on their cadence; every writer stays disarmed until you arm it. The read paths are harmless, because discovery and the monitor write nothing to Allegro.

Runtime toggles

Every writer that reaches Allegro is governed by a persisted, operator-flippable toggle, stored as a one-row allegro_settings singleton. 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.

Precedence

The environment, and the boot-time plugin option, is a hard override that can only force a writer off. It never arms one:

effectiveEnabled = persistedEnabled && !forceDisabled

• persisted on + env unset -> on
• persisted on + env force-disable -> off, because 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 variable 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.

Invoice attach is the one writer that ships on, because by the time this plugin hears about an invoice the document already exists as a legal record, so delivering it is the safe default. It is inert until an invoicing module is wired and emitting events.

Sync configuration fields

Nine settings are editable from Settings -> Allegro on the same singleton: the pricing mode, the two automation rule names, the two SRP sources, the change cap, the marketplace id and the sales-channel scope. An edit persists and takes effect on the next run, no redeploy.

A store that never touches these fields behaves exactly as before: every persisted column starts null, and null falls through to the medusa-config.ts option.

Precedence for a value, not 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. Clearing a field in the admin writes null, which falls back to the medusa-config.ts option rather than to an empty value.

Two fields are wiring-critical

Editing marketplaceId or salesChannelId re-scopes which Medusa products this plugin matches against Allegro offers. A wrong value breaks the mapping silently rather than producing an obviously bad result. Both stay editable, with the env lock as the escape hatch: 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.

Two invariants are enforced on every write

The standard and promoted rule names must differ, and at most one SRP source may be set. Both already existed as boot-time checks, and both are now also enforced on every admin write, because persisting one field independently of the other can newly create a collision the boot-time check never saw. The write is rejected rather than silently accepted.

Turning the writers on

Every writer ships disarmed, so the loops run read-only until you arm each one. The safe order, and why each step comes where it does:

1. Connect the account with the write scope. Without it every command answers 403 and the admin raises the reconnect banner.
2. Leave the writers disarmed while you prepare. That is the fresh-install default, so there is nothing to do unless you upgraded with writers already armed. If you are cutting over from another system that currently writes to Allegro, set the force-disable variables so no toggle flip can arm a writer until the old system is retired. Two systems writing to one catalogue is the worst possible state, and each writer is separate.
3. Let discovery and the monitor run. Both are read-only. Resolve every conflict on the Offers page, and look at what the price mode and drift actually say about the catalogue. This is the step that turns arming the writers into a decision rather than a leap.
4. Fill in the category rates. Until a category has both, every offer in it is skipped with missing-break-even.
5. Configure the SRP source, and check that variants actually carry a value. Without it every offer is skipped with missing-srp.
6. Create the two price-automation rules on the Allegro account and set automationRules to their names. Until then price sync is inert by construction.
7. Arm the writers - stock first, then prices. A wrong quantity is recoverable in one run; a wrong price may already have sold something. Raise changeCap only once you have watched the push history and believe the run. Arm the order drain, fulfillment write-back and invoice attach when you are ready for each.

Stopping the writers, now

Set the relevant variable and redeploy the process environment:

ALLEGRO_PRICE_SYNC_DISABLED=1      # price-automation commands
ALLEGRO_STOCK_SYNC_DISABLED=1      # quantity-change commands
ALLEGRO_ORDERS_SYNC_DISABLED=1     # the order drain
ALLEGRO_INVOICE_ATTACH_DISABLED=1  # attaching invoice PDFs

A disabled loop records that it was disabled on its state row, so "disabled" stays distinguishable from "broken" - both look like "nothing happened" from outside.

The variable can only ever disable, never enable. The resolution is option === true || envIsTruthy, so ALLEGRO_PRICE_SYNC_DISABLED=0 does not re-arm a loop whose option is true. What re-arming takes therefore depends on how your config was written, and it is worth settling before you need it under pressure:

// Pattern A - option pinned. Re-arming means editing config and redeploying.
priceSyncDisabled: true,

// Pattern B - option derived from the same variable. Re-arming is one env change,
// and the incident switch still wins, because =1 also yields option true:
//   unset -> true (disabled)    =1 -> true (disabled)    =0 -> false (armed)
priceSyncDisabled: process.env.ALLEGRO_PRICE_SYNC_DISABLED !== "0",

Pattern B is the better default for a staged cutover: one variable is both the pre-cutover hold and the arming switch, so no config edit stands between an operator and a working sync. Pattern A is right when you want arming to require a code review. Pattern B must compare against "0" explicitly rather than coercing, because Boolean(process.env.X) is true for the string "0", which would pin it disabled forever.

Note that ordersSyncDisabled does not stop the fulfillment write-back and does not stop the invoice attach - each has its own switch. It does stop the invoice retry sweep, which runs at the end of the drain. To stop every write to Allegro, disconnect the account.

Reading a loop that looks stuck

Check the state row's status on the settings page:

• running and not moving. A crashed run holds the claim for up to six minutes, after which the next tick takes it over as stale and logs that it did. Staleness is measured from claim_heartbeat_at, which a live run bumps at least once a minute, so a long but healthy run keeps its claim instead of being taken over mid-flight.
• running, with a log line about losing the claim. A run discovered it had been taken over and stopped without writing anything further, including its own outcome. Nothing is lost; the abandoned work replays.
• idle or error with a kill-switch message while a run is in flight. A skip arriving while another run holds the claim deliberately does not touch the state row, and logs that it declined to. Writing it would have released that run's claim and let the next tick start a second concurrent run.
• error with SYSTEMIC in the message. The loop is waiting on Allegro. Nothing was skipped and nothing quarantined; it retries on its own.
• ok with zero counters. Nothing to do, which is different from broken. The counters are on the health table precisely so those two are distinguishable.
• idle with a kill-switch message. Working as configured.

The manual push budget

POST /admin/allegro/offers/:sku/push shares the scheduled loop's blast radius. Manual pushes are counted over a rolling hour, and once that count reaches changeCap further pushes are refused with HTTP 429 and a Retry-After of one hour.

This exists for scripts rather than for people. Each call takes the sync claim, so calls serialise - but serialising is not bounding, and a loop over this route would otherwise reprice the entire catalogue, walking straight around the cap that exists to stop a bad plan doing exactly that. The count comes from pushed_by on the audit table, so the plugin's own loops never consume an operator's budget and the cap survives a restart.

If you legitimately need to push more than that in an hour, raise changeCap - which raises it for the scheduled loop too, deliberately, because that is the same decision.