Hooks
Intro
Hooks watch for something that happens later and then act. Automation Rules run when an order or shipment is evaluated (import, update, print, split, merge). A hook runs when a chosen event fires: stock moved, a shipment appeared, or a shipment changed status.
Open Advanced → Hooks. Each hook reads as one sentence: when the trigger fires, and an optional condition matches, then do the action.
Purpose
- Keep a Low stock tag accurate after quantities change, not only at the moment the shipment was created
- Tag the order when a shipment moves to Shipped, so a follow-up team can see it
- Raise one alert when a shipment is created with a tag that needs a person
Create a hook
- Click New hook. Name it by its job ("Low-stock tag follows inventory") and add an optional description.
- Pick a When trigger and, if the trigger offers them, narrow it (which statuses, changed from / changed to).
- Optionally pick a Condition — the same saved conditions as Automation Rules. No condition means every shipment the trigger produces. Only active conditions are listed.
- Pick a Then action and fill its settings. The editor shows the sentence before you save.
- Create. A new hook is a draft and does nothing until you switch it on. Test it first with Run now on shipments….
Triggers
| Trigger | When it fires | What it acts on |
|---|---|---|
| Inventory is updated | A product sync changed the available quantity of one or more variants at a location | Open shipments that contain those variants. Awaiting only, unless you also tick On hold. Shipped, cancelled, and merged shipments are never included |
| A shipment is created | Order import, a split, a merge, or a manual shipment | That shipment, after the built-in automation rules have already run. A shipment deleted again before the hook runs (an empty shell) is ignored |
| A shipment changes status | The shipment moved between statuses (awaiting, on hold, shipped, picked up, cancelled, merged) | That shipment. Changed to and Changed from can limit it to one transition; leave them empty for any change |
Events are collected and run together, about every 20 seconds, so a burst of inventory updates becomes one pass.
Actions
| Action | What it does |
|---|---|
| Add or remove tags | Adds the chosen tags to, or removes them from, every matched shipment — or the orders behind those shipments. A tag that is already in the wanted state is left alone. The tag timeline records the hook as the source |
| Re-run automation rules | Evaluates rules again and applies their tag and append actions. Stock-sensitive rules only means rules whose condition reads Location available quantity — no extra flag. Selected rules uses the rules you pick. All active rules skips split rules. Split rules are never re-run from a hook, because that would move items. Only awaiting shipments are modified |
| Raise an alert | Puts one alert in the inbox for the run, with the matched shipments attached. Title and message can use {count} (how many shipments) and {hook} (the hook name). While that alert is still open, later runs increase its count instead of adding new alerts |
Test, then switch on
- Open the hook's menu → Run now on shipments… and pick one or two shipments that should match.
- Open Run history (or Recent runs in the header) and read what the hook did.
- Switch the hook on. From then on it reacts to new events. It does not walk back through shipments that already exist — use Run now for those.
Move up / Move down set the order when several hooks share a trigger. The one higher in the list runs first.
When a condition stops matching
Add or remove tags can undo itself. Tick the reverse option (it only appears when the action supports it and a condition is selected). A shipment that matched and later stops matching gets the opposite: tags this hook added come off, tags it removed go back on. A shipment that never had the tag is left alone.
Re-running rules and raising an alert do not undo. An open alert stays until someone resolves it.
The list
Filter by trigger. Each card shows the sentence, Draft when it is off, the run count, and the last run (status and time). Two warnings can appear above the list:
- Hooks are paused on this server — they are saved, and nothing fires until an operator turns them back on.
- Events are waiting but nothing is processing them — the hooks are fine; the queue worker for that queue is not running. The message names the queue and the worker command.
A hook whose condition has been deactivated shows Condition inactive and will not match until that condition is switched back on.
Who can use it
A Pro and Enterprise feature, on the same plan as automation rules. Permissions View hooks and Manage hooks. The AI assistant, with the Operations module and changes enabled, can list hooks, create them as drafts, test one on a shipment, and switch it on — turning a live hook on comes back as a preview you confirm.
Troubleshooting
| What you see | What to check |
|---|---|
| The low-stock tag never updates after a sale | The hook is on, its trigger is Inventory is updated, and the action re-runs the stock-sensitive rules. Those rules must use Location available quantity. Inventory webhooks have to be arriving — see Inventory Management |
| Run now did nothing | The shipment is not awaiting, it does not contain a variant the trigger cares about, or the condition does not match |
| Events are waiting | The queue worker named in the banner is not running |
| A shipped box was tagged | Inventory is updated never includes shipped shipments. A status changed or shipment created hook might. Narrow Changed to, or add a condition |
Related
- Automation Rules — the rules a hook can re-run, and the conditions it can require
- Tags — the labels a hook applies
- Alerts — where Raise an alert lands
- Inventory Management — the sync that fires Inventory is updated