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.

8 min readUpdated 3 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, download the extension build, 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 CodeCanyon purchase code and Envato username for item 44624493
    • Outbound HTTPS from the server to the licence host
    • Shell access to the box — the extension build is applied on the server
    • 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. Open the extensions screen. Sign in to the admin panel and go to System → Extensions (/admin/system/extension). E-commerce is listed with a licence badge and a disabled toggle.

  2. Activate the licence. Open the E-commerce card. Enter your Envato username and the purchase code. Activation posts to /api/admin/system/license/activate with the product id 44624493 and verifies against the licence host. The enable toggle stays disabled until this succeeds.

  3. Install the latest version. From the same card, run the update. It downloads the current build for your licence and applies it to the server tree. Do not interrupt it.

  4. Enable the extension. Toggle it on. That writes status = true on the ecommerce row in the extensions table and clears the platform cache so every process sees it.

  5. Restart the platform. From the project root:

    pnpm restart

    The cache clear covers the licence gate, but new routes and models are read at boot. If /admin/ecommerce 404s after enabling, this is the step you skipped.

  6. 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 extensions screen is disabled until the licence verifies. 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

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)

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

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 extension card: check for an update, then run it. It downloads and applies the new build for your licence.

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 on boot. Restart after an update so the new routes load.