Install on Magento 2
Install the ShopAssist module with Composer, pair each website with a code, and enable stock per source, returns and customer cancellations.
Requirements
- Magento Open Source / Adobe Commerce 2.4.6: >=2.4.6 <2.4.7 (PHP 8.1–8.2)
- Magento Open Source / Adobe Commerce 2.4.7: >=2.4.7 <2.4.8 (PHP 8.2–8.3)
- Magento Open Source / Adobe Commerce 2.4.8: >=2.4.8 <2.4.9 (PHP 8.3–8.4)
- Magento Open Source / Adobe Commerce 2.4.9: >=2.4.9 <2.5 (PHP 8.4–8.5)
- Mage-OS: >=1.0 (PHP 8.2–8.5)
- Latest plugin version: 1.0.0
- Composer access to your Magento root and a deploy process (production mode needs compilation and static content deploy).
- Magento cron must run: the module uses it to send changes and heartbeats.
- HTTPS on the storefront, and inbound requests from the ShopAssist egress IPs allowed through your firewall or WAF.
- An admin role with access to Stores → Configuration at website scope.
Install
Typical setup: A Composer deploy by your developer
1.Install the module with Composer
Run this in your Magento root. Add the optional modules for multi-source inventory (
coec/module-shopassist-inventory), returns (coec/module-shopassist-rma, Adobe Commerce) and customer cancellation (coec/module-shopassist-order-cancellation) if you use them.composer require coec/module-shopassist2.Enable the module and deploy
Run the upgrade and flush the cache. In production mode also compile and deploy static content. Magento cron must run.
bin/magento setup:upgrade bin/magento setup:di:compile bin/magento setup:static-content:deploy bin/magento cache:flush3.Paste the pairing code
In the ShopAssist dashboard, create a pairing code. In the Magento admin open Stores → Configuration → ShopAssist at website scope, paste the code and click Connect. Connect one ShopAssist store per website.
Optional modules:
| Module | Adds | Needs |
|---|---|---|
coec/module-shopassist-inventory | Stock per source (MSI) and pickup locations | Magento Inventory (MSI) |
coec/module-shopassist-rma | Return requests through Adobe Commerce RMA | Adobe Commerce Beta |
coec/module-shopassist-order-cancellation | Customer cancellation through Magento's order cancellation | sales/cancellation/enabled |
The module adds no storefront JavaScript, RequireJS configuration or Knockout templates, so it works with Luma, Hyvä (including the CSP variant) and Breeze without a compatibility module. Full-page cache and Varnish are safe: the widget fetches everything personal after the page loads.
Connect
- In the ShopAssist dashboard, Add store → Magento 2, then Generate pairing code. The code is valid for 15 minutes.
- In Magento admin, switch the scope to the website you are connecting, open Stores → Configuration → ShopAssist, paste the code and click Connect.
- The module creates a Magento Integration for that website with only the ShopAssist API resources, and ShopAssist calls your store back to confirm it can reach it. The dashboard switches to "Syncing".
Connect one ShopAssist store per website. Each website is paired from its own website scope with its own code and its own Integration, so reconnecting one never affects another. If connecting fails, the message links to the matching connection error.
Verify
- Stores → Configuration → ShopAssist shows "Connected" with the store name.
- The dashboard shows the first sync progress; product counts match your catalog.
- The launcher appears on your storefront (not on checkout pages: the widget is never rendered on checkout).
Signed-in customers
Signed-in customers are recognised automatically through the module's identity endpoint. The endpoint is called after the page loads with Magento's form key, so it is safe with full-page cache and Varnish. Customer account sharing across websites is respected: orders are only shown for the connected website. See Magento identity.
Stock per location
Install coec/module-shopassist-inventory to send stock per MSI source. Sources assigned to the website's stock become locations; sources with in-store pickup are shown as stores. Choose which ones shoppers see in Catalog → Locations.
Note
Magento's source quantities are physical quantities: they don't subtract reservations for orders that are not shipped yet. The assistant therefore describes stock per store conservatively, and the online salable quantity is used for "can I order it online?".
Without MSI, you can still provide store stock with a local inventory feed or the Catalog Push API.
Updating
Update with composer update coec/module-shopassist (and the optional modules), then run the same deploy commands as for the install. The dashboard tells you when your module is more than two minor versions behind. See plugins for the update policy.
Uninstall and data removal
Run bin/magento module:uninstall Coec_ShopAssist --remove-data (optional modules are removed first). It disconnects every connected website, deletes the Integrations, removes the database triggers and tables and the shopassist/* configuration. module:disable alone keeps the data and sends nothing; the dashboard then reports a missing heartbeat after two hours. ShopAssist deletes the store's data 30 days after the disconnect. See uninstall and data removal.
Troubleshooting
- Connection errors, especially the offloader header and missing ACL resources
- Cron not running
- The widget is not showing: custom themes that remove the
before.body.endcontainer need a layout<move> - Signed-in customers are not recognised
Last updated on