A blank aio app init gives you a hello-world action and nothing Commerce-specific. Authentication to Commerce, event registration, retries and a sensible folder layout are all left to you. Adobe publishes starter kits that solve most of that already, and for a Commerce integration I'd start from one every time. This episode compares the options, then takes the integration starter kit from clone to Stage. About an hour, most of it in the terminal.
I went straight to the integration starter kit, so there's no switching story here. The comparison below is what I read before choosing.
You’ll need
- An Adobe organisation with App Builder access, and a project created from the App Builder template in Developer Console (it comes with Stage and Production workspaces)
- Node.js LTS, the Adobe I/O CLI, and
aio logindone - A Commerce instance you can configure, with the eventing modules available (needed for the onboarding step)
Pick the right starting point
aio app initwith a template: a generic action, optionally with a React UI. It's best for learning the platform or for apps that aren't Commerce integrations.- Adobe Commerce integration starter kit: a ready-made structure for syncing Commerce with a back-office system in both directions. It includes event registration scripts, Commerce API clients and a consistent pipeline for every event. This is the one for ERP, PIM, CRM or marketplace work.
- Adobe Commerce checkout starter kit: examples for payment, shipping and tax methods built on webhooks. Pick it when the job is checkout behaviour, not data sync.
For the rest of this series I use the integration starter kit, because most of what I port out of Adobe Commerce (Magento 2) is integration code.
Clone it and bind it to your workspace
Download the Stage workspace configuration from Developer Console (Download all), then:
git clone --branch legacy https://github.com/adobe/commerce-integration-starter-kit.git order-sync
cd order-sync
aio app use ~/Downloads/<project>-Stage.json
aio where
npm install
The legacy tag of the kit's repository is the version with the env.dist and onboarding scripts this episode uses. Since July 2026 the kit's main branch installs through App Management instead, with events declared in app.commerce.config.ts. aio app use writes .aio and the Runtime part of .env (episode 1). It also switches the CLI's global selection, which is what aio where prints, so straight after binding it should say Stage. Save the same JSON as scripts/onboarding/config/workspace.json too, where the onboarding script expects it.
Fill in the environment from env.dist
The kit ships an env.dist listing every variable it expects: your Commerce base URL, Commerce credentials, and the details its onboarding script needs. Copy the variables into .env and fill them in. Use OAuth credentials from a Commerce integration on PaaS, or IMS credentials on Adobe Commerce as a Cloud Service (ACCS), the SaaS edition, as the README for your version describes.
Tip: Create a dedicated Commerce integration with only the API resources the app needs. Don't reuse an admin account's access.
Read how an event flows through the kit
Each entity and direction has its own folder under actions/. For example, customer events coming from Commerce sit apart from customer events coming from the external system. Inside, every event goes through the same small pipeline:
- validate: reject payloads that are missing what you need;
- transform: map Commerce fields to the other system's shape;
- send: call the external API;
- pre and post hooks: your extra logic before and after.
This consistency is the real value of the kit. Twenty integrations built this way look alike, which you can't say about twenty hand-written Adobe Commerce observers.
Deploy to Stage, then run the onboarding
Deploy the actions first, then let the kit's script create the event provider and the registrations in Developer Console, so you don't click them together by hand:
aio app deploy
npm run onboard
Then subscribe Commerce to the events the kit listens for, using the subscribe script the README names for your version. Episode 6 covers the eventing side in detail.
Prove it end to end
Create a test customer in the Commerce admin, then check that the event arrived:
aio app logs
If nothing shows, open the registration's Debug Tracing tab in Developer Console first: it lists each delivery with the response code your action returned. On my Stage workspace, runs started by I/O Events didn't show up in aio rt activation list or aio app logs, but the delivery trace behind that tab had them, so an empty aio app logs doesn't prove the event never arrived. Then check three things in order. Is Commerce connected to your workspace (Stores > Configuration > Adobe Services > Adobe I/O Events)? Is the event subscribed (bin/magento events:list)? Is the registration in Developer Console pointing at the deployed action?
Commit what's yours, ignore what isn't
Commit the code and env.dist. Never commit .env or .aio. Keep a short README.md at the top of the repository with your own setup steps: the next developer reads that, not the upstream kit's.
Tested on: a Stage workspace, where I deployed and onboarded the starter kit before I wrote this episode.
Not tested: these exact steps on the legacy tag since then, so follow the kit's README where it differs.
Done!
You have a real Commerce integration skeleton running on Stage. Episode 3 covers what replaces cron, config and custom tables when your code leaves Adobe Commerce.
