MMashDiv

Install and enable

Activate the E-commerce licence, enable the extension, grant the permissions, decide which wallet types you sell in, and prove the storefront works before you publish a product.

13 min readUpdated 26 August 2026install, licence, extension, permissions

E-commerce ships as a licensed extension of an existing Bicrypto install. There is no separate installer and no separate service. You activate a licence, install the release, apply it with pnpm updator, flip a switch, and the routes and menus appear.

Everything below assumes core is already installed, running and reachable over HTTPS. If it is not, do Bicrypto install first — nothing on this page will work against a half-configured platform.

Before you start

  • A working Bicrypto install: backend, frontend and cron all up
  • Admin access with the edit.extension and edit.settings permissions
  • Your purchase code for Ecommerce (product ID 44624493), from your MashDiv dashboard
  • Outbound HTTPS from the server to the licence host — or, without it, the licence certificate downloaded from your MashDiv dashboard for the License File route
  • Shell access to the box — the installed release is applied on the server with pnpm updator
  • A decision on which wallet types you will price products in
  • Working outbound mail — order confirmations go through core's mail queue

Activate and enable

  1. The Ecommerce card — click it to open the product page
  2. Its switch stays disabled, reading Activate license first, until the licence is activated

  1. Open the Extension Manager. Sign in to the admin panel and go to Admin → System → Extension Manager (/admin/system/extension); the page heading is Add-ons & Integrations. On the Extensions tab, or by searching for Ecommerce, find the Ecommerce card and click it. Until its licence is activated the card's chip reads Activate and its switch is disabled with the tooltip Activate license first.

  2. Activate the licence. On the product page press Activate License. The licence screen opens with the product's name and its Product ID, 44624493. Paste the purchase code from your MashDiv dashboard, optionally an email address for update notifications, and press Activate License. The screen confirms License Activated! and sends you back to the product page a couple of seconds later. If the server has no outbound access, the License File tab on the same screen takes the licence certificate downloaded from your MashDiv dashboard instead: place it as license.txt in the /lic folder at the project root, then press the button on that tab.

    1. Paste the purchase code here
    2. Activate License — then wait for the redirect back to the product page
    3. License File — the route for a server with no outbound HTTPS

  3. Install the release. Back on the product page, now licensed, the Overview tab has a release panel. If it offers Install v…, press it; if it says Up to date on a product you have only just licensed, press Check for Updates once, then install whatever it offers. The Releases tab holds the notes for the version you are being offered — read them first. Do not interrupt the download.

    Install downloads the release, verifies it and extracts it over the project root. It runs no migrations, builds nothing and restarts nothing, so finish it from a shell on the server:

    pnpm updator

    That is the finalise chain — stop, dependencies, schema, seed data, frontend build, start — and it is what makes the store's tables, routes and screens exist: new routes and models are read when the backend starts, and this is what starts it. If /admin/ecommerce 404s after enabling, this is the step you skipped. If the panel still says Up to date after the check there is nothing to download; go straight to the next step.

    1. Check for Updates, then Install v… when it is offered
    2. Releases — the notes for the version you are about to install
    3. The Enabled switch — step 4, not yet

  4. Switch it on. Turn the Enabled switch on — in the product page heading, or on the Ecommerce card in the Extension Manager, which is usable now that the licence is verified. This is what makes E-commerce Platform appear in the admin menu under Extensions → Marketplace Solutions, /admin/ecommerce answer with the store dashboard, and Store appear in the user navigation at /ecommerce. It takes effect without a restart; the next section lists exactly what changes.

  5. Confirm it answers. As an admin, load /admin/ecommerce. You should get the store dashboard rather than a licence error. Then load /ecommerce as a signed-out visitor — the storefront landing page is public.

The switch on the Ecommerce card in the Extension Manager is disabled until the licence is activated — its tooltip reads Activate license first. If activation failed, the switch simply will not move and there is no separate error to chase. Fix the activation, not the switch.

What enabling actually changes

Three things, and it is worth knowing which is which when one of them is missing:

  • The licence gate opens. Every request under /api/ecommerce and /api/admin/ecommerce passes an extension-licence check. Without a valid licence it answers 403 with Extension license required and the product id — not 404, so an extension you thought was installed looks like a permissions problem.
  • The admin menu appears. /admin/ecommerce gains Dashboard, a Catalog group (Products, Categories, Reviews, Wishlist), a Sales group (Orders, Discounts, Shipping) and Settings.
  • The storefront menu appears. /ecommerce gets Home, Products and Categories for everyone, plus Orders and Shipping once signed in. Active categories are pulled live and become child items under Categories, so the storefront navigation grows as you publish.

Grant the permissions

E-commerce adds 26 permission keys. A Super Admin holds all of them automatically; every other role holds none until you say so.

Go to CRM → Roles, edit the role, and grant what that role actually needs. The minimum useful sets:

Job Grant
Read-only reporting access.ecommerce.dashboard, view.ecommerce.order, view.ecommerce.product
Catalogue editor view/create/edit/delete.ecommerce.product and the same four on category
Fulfilment view.ecommerce.order, edit.ecommerce.order, plus view/create/edit.ecommerce.shipping
Moderation view.ecommerce.review, edit.ecommerce.review, delete.ecommerce.review
Promotions view/create/edit/delete.ecommerce.discount

It covers cancelling and rejecting orders, which refunds the buyer from your platform wallet and restores stock. It also covers attaching licence keys and download links to somebody's purchase. Treat it as a finance permission, not a support one.

The full list, and the rule that derives each key from its admin path, is in the API and permissions reference.

Decide your wallet types

  1. Open the create form

Every product carries a walletType and a currency, and the buyer must hold a wallet of exactly that pair. Get this wrong and customers see Insufficient balance on products they can plainly afford.

Wallet type What it spends Available
FIAT Fiat balances (USD, EUR, …) Always
SPOT Spot exchange balances Always
ECO Funding/ecosystem balances Only if the Ecosystem addon is installed

The product form reads its currency list from /api/admin/finance/currency/options?type=<walletType>, so the currency dropdown re-populates when you change the wallet type. If it is empty, that wallet type has no enabled currencies in core — fix that in Finance first.

Checkout groups cart lines by wallet type and currency and validates each group against its own wallet. A cart mixing a FIAT/USD product with a SPOT/USDT product needs the buyer to hold funded balances in both, or the whole checkout fails. A single-currency catalogue avoids an entire class of abandoned carts.

Gate purchases behind KYC (optional)

  1. Open the level you want purchases restricted to

The store honours one KYC feature flag: order_ecommerce, shown in the level builder as Marketplace Purchases. Both order routes assert it before they touch a wallet, so an under-verified customer is refused at checkout with a KYC message rather than a payment error.

Browsing, wishlists and reviews are not gated by it. If you want purchases restricted, add Marketplace Purchases to the appropriate level in CRM → KYC → Levels. Leave it off every level and anyone verified enough to hold a funded wallet can buy.

Configure the store

Two settings genuinely change what customers are charged, and both default to on with a value you probably do not want:

  • Tax — ecommerceTaxEnabled with ecommerceDefaultTaxRate (default 10%, applied store-wide to the discounted subtotal).
  • Shipping — ecommerceShippingEnabled with ecommerceDefaultShippingCost (default 10, charged once per checkout that contains a physical product).

Set them on /admin/ecommerce/settings before you take a single order. The full list, including the three display switches that are wired to nothing, is on Store settings.

Prove it end to end

  1. The downloadable order, created COMPLETED

Do this on a real install before you announce the store. It takes ten minutes and catches every common misconfiguration.

  1. Create a category. /admin/ecommerce/category → Create. Name, description and an image. Leave it active.

  2. Create one downloadable product. Price it at the smallest sensible amount in a currency you can fund a test account with. Set inventory to anything — it is ignored for downloadable items.

  3. Create one physical product in the same currency, with inventory of 2.

  4. Fund a test customer's wallet in that exact wallet type and currency.

  5. Buy both from the storefront. Add to cart, check out with a shipping address. You should get two orders — one COMPLETED (the download) and one PENDING (the physical item) — and one shipping charge across both.

  6. Check the money moved. The buyer's wallet is down by the total. The Super Admin wallet is up by the discounted subtotal plus a separate pass-through credit covering shipping and tax.

  7. Attach the download. Open the completed order in /admin/ecommerce/order, set the download options, then confirm the customer's order page offers it. Until you do this the buyer sees "Nothing has been attached to this purchase yet".

  8. Cancel the physical order. Confirm the buyer's wallet is made whole, the platform's revenue is reversed, and inventory goes back to 2.

  9. Check the email arrived. Order confirmation and status-update mails go through core's queue using the OrderConfirmation and OrderStatusUpdate templates. If they did not arrive, the store is fine and your mail configuration is not.

Updating later

Updates are applied from the same product page: open the Ecommerce card in Admin → System → Extension Manager, press Check for Updates on the Overview tab, read the notes on the Releases tab, then press Install v…. Install downloads the release, verifies it and extracts it over the project root — and changes nothing until you finish it from the project root:

pnpm updator

Updates are applied one version at a time; if several are pending the panel offers the next one and re-checks after each.

Extension updates extract over the existing tree. They do not delete files that were removed upstream. A build error naming a file that no longer exists in the release is almost always a leftover from an older version, not a broken download.

Nothing in the store schema needs a manual migration — the tables are synced from the models when the backend starts, and pnpm updator restarts it for you, so the new routes load with the same command.