# 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.

Source: https://shopassist.coec.dk/docs/install/magento-2 · Updated 2026-10-01

## Requirements [#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](/docs/security/egress-ips) allowed through your firewall or WAF.
* An admin role with access to **Stores → Configuration** at **website** scope.

## Install [#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.

```bash
composer require coec/module-shopassist
```

**2. 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.

```bash
bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento setup:static-content:deploy
bin/magento cache:flush
```

**3. 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 [#connect]

1. In the ShopAssist dashboard, **Add store → Magento 2**, then **Generate pairing code**. The code is valid for 15 minutes.
2. In Magento admin, switch the scope to the **website** you are connecting, open **Stores → Configuration → ShopAssist**, paste the code and click **Connect**.
3. 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](/docs/troubleshooting/connection-errors).

## Verify [#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).

[Send a test message](/app/go/playground)

## Signed-in customers [#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](/docs/orders-and-identity/magento-2).

## Stock per location [#location-stock]

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](/docs/install/generic/product-feeds#local-inventory) or the [Catalog Push API](/docs/install/generic/catalog-push-api).

## Updating [#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](/docs/plugins) for the update policy.

## Uninstall and data removal [#uninstall]

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](/docs/install/uninstall-and-data-removal).

## Troubleshooting [#troubleshooting]

* [Connection errors](/docs/troubleshooting/connection-errors), especially [the offloader header](/docs/troubleshooting/connection-errors#signature_invalid_check_offloader_header) and [missing ACL resources](/docs/troubleshooting/connection-errors#acl_missing)
* [Cron not running](/docs/troubleshooting/sync-issues#cron_not_running)
* [The widget is not showing](/docs/troubleshooting/widget-not-showing): custom themes that remove the `before.body.end` container need a layout `<move>`
* [Signed-in customers are not recognised](/docs/troubleshooting/signed-in-customers)