Every earlier episode was a building block. Now they go together on a module that sends new orders to an external fulfilment API. Most Adobe Commerce (Magento 2) projects have one like it. Plan on half a day.
I ran this port on a Commerce Cloud staging, with an App Builder Stage workspace next to it. The module is an observer on sales_order_place_after that POSTs the order to an ERP, with a cron job and a retry table for the calls that fail. The app version listens for the same event and sends the same order. Both pointed at one fake ERP, so I could compare what each one sent.
What the side-by-side run showed:
- Payload: the order lines and the address were identical, once the subscription asked for
order.addresses. - Timing: on a normal order the app delivered 9.1 s after the module. The module sends inside checkout; the app sends after it.
- Retries: with the ERP address broken for both, both queued the order. The module's budget is 6 attempts, 10 minutes apart, and it delivered on attempt 6, its last one. The app resent from its 10-minute retry run.
- Switch-over: with the module disabled, a new order reached the fake ERP from the app only.
You’ll need
- A module to port, with an observer that calls an external API
- Everything from episodes 1 to 9
- The Playwright suite from the Playwright regression checks post
Write down what the module does
Before moving anything, list its behaviour: which event triggers it, what data it sends, what it does on failure, which config it reads, what it shows in the admin. That list is your acceptance test, and the one place the two versions have to agree.
| In the module | In App Builder | Episode |
|---|---|---|
Observer on sales_order_place_after | Commerce event subscription, with only the fields the API needs, handled by an action | 6 |
| Cron job that retries failed calls | Alarm trigger that runs the retry action | 3 |
| Failed deliveries | The export_runs collection; State keeps only the lock | 4 |
| API keys in Commerce config | The action's environment, injected at deploy time | |
| Status in the admin | Admin UI SDK page: recent deliveries, failures, a retry button | 9 |
Replace the observer with an event
Subscribe to the order event with only the fields the external API needs (episode 6). Fulfilment can’t ship without an address, so here the address is one of them. Your action receives the event and calls the fulfilment API. The order sits under order in this event, so every field starts with order.. --fields=order.items sends every field of every item; once you know which ones the API reads, list just those with order.items[].sku notation. A path that matches nothing is dropped without an error (episode 6), so place one test order and look at the payload before go-live. That check caught one for me: order.shipping_address arrived as null, because the order data has no such key. The addresses sit under order.addresses, and the mapper picks the shipping one from there.
bin/magento events:subscribe observer.sales_order_place_after \
--fields=order.increment_id --fields=order.items --fields=order.addresses
If the project has two event providers, add --providerId with the one your registration listens on. Without it the subscription goes to the default provider, and the app never sees the event.
Move the retry logic
The module probably retried failed calls with a cron job. In App Builder, an alarm trigger from episode 3 runs the retry action, and failed deliveries live in the export_runs collection from episode 4, where the admin page can read them. State keeps only the lock. Keep every call idempotent, using the order number as the key.
The real run caught one bug here. With aio-lib-db 1.1.0, findOne does not return null when nothing matches. It throws a DbError ("Document not found"), so the first lookup for a new order made the action answer 500. I/O Events redelivers a 500, so the events went through once the fix was deployed. The fix is a small wrapper that treats exactly that error as null and rethrows the rest, so a real outage is not hidden:
const NOT_FOUND = /failed(?: with code 404)?: Document not found$/
async function findOneOrNull (runs, filter) {
try {
return await runs.findOne(filter)
} catch (e) {
if (e && e.name === 'DbError' && NOT_FOUND.test(String(e.message))) return null
throw e
}
}
Move the config and the status page
API keys move from Commerce config to the action’s environment, injected at deploy time. The admin page from episode 9 shows recent deliveries, failures and a retry button.
Run both side by side, then switch
Deploy the app with the external call pointed at a sandbox, and run it alongside the module for a few days. Compare what each one sent. When they match, disable the module’s observer and point the app at production.
On a shared staging, the app side exports every order, because it has no test filter. Mine exported an order that wasn't one of my test orders. Filter on your side, or use a staging of your own.
Weigh what you gained against what you added
Better: the module no longer blocks order placement, an upgrade can’t touch it, and the logic is testable on its own. Harder: another deployment pipeline, another place to look when things fail, and latency you now have to monitor. For a module like this, the trade is worth it. For a module that changes checkout totals, it wouldn’t be: episode 0 covers when to keep a module instead.
Tested on: a real Stage workspace, against a Commerce Cloud staging and a fake ERP. The export-order action, registered as the only consumer of sales_order_place_after, received real orders and sent them, with the nested --fields order.items and order.addresses. The export-order-retry alarm ran every 10 minutes. The export_runs collection recorded the sent rows. In the side-by-side run the lines and the address matched the module's, the app was 9.1 s behind the module on a normal order, and the failure test queued the order in both senders and delivered it from both. After the module was disabled, only the app sent.
Not tested: the dead state when either side runs out of retries, the admin Retry button, and extension packaging. The current list is in the repo README.
Done!
That’s the foundations, from a first action to a ported module. From here the series continues as a developer log.
