MMashDiv

E-commerce

Sell physical and digital goods inside Bicrypto — what the addon adds, how wallet-funded checkout works, what it deliberately does not do, and where to start.

6 min readUpdated 3 August 2026ecommerce, store, orders, downloads

E-commerce turns your Bicrypto install into a shop. You publish products, customers browse a storefront at /ecommerce, and they pay from a wallet they already hold on your platform. Physical goods land in a fulfilment queue; digital goods complete immediately and wait for you to attach the file or licence key.

It is a genuine store, not a card checkout bolted onto the side. That has one consequence worth understanding before you plan anything: a customer who has not funded a wallet cannot buy from you. There is no "pay with card" button on the checkout page. Funding happens through core's normal deposit flow, and the store spends what is already there.

What it requires

E-commerce is not standalone. It installs into an existing Bicrypto installation and uses core's users, wallets, KYC levels, notification templates, mail queue and permission system.

  • Bicrypto core — required. Install and configure that first.
  • Ecosystem — optional. Only the ECO (funding) wallet type depends on it; without Ecosystem the product form offers FIAT and SPOT only.
  • Affiliate/MLM — optional. Two seeded reward conditions (ECOMMERCE_PURCHASE) pay referrers on store purchases if you run it.

No extra database, no extra process, no extra port. E-commerce adds eleven tables to the same MySQL schema and its routes to the same backend.

What you get

  • Catalogue — categories and products, two product types (physical and downloadable), per-product price, currency and wallet type, inventory counts, slugs generated for you, soft deletes with restore.
  • Storefront — a landing page, product and category browsing, search and filters, wishlists, a cart that lives in the browser, and a checkout that quotes shipping and tax before it charges.
  • Orders — a four-state lifecycle with a guarded transition table, an all-or-nothing checkout, atomic stock decrements, and cancel/reject that refunds the buyer and puts the stock back in one transaction.
  • Digital delivery — per-order-item attachment of a licence key, a download link, or both, plus a session-checked file streamer for anything hosted on your own box.
  • Shipping — a flat store-wide shipping fee, shipment records you create and assign to orders, per-order shipping addresses, and a buyer-facing tracking timeline.
  • Discounts — per-product codes, four validity rules, one-use-per-customer enforcement, and three discount shapes (percentage, fixed amount, free shipping).
  • Reviews — verified-purchase only, one per customer per product, with an admin moderation queue.
  • Analytics — a store dashboard with revenue, orders and customer charts over a date range you choose.

How a sale actually works

This is the part that surprises people, so read it once:

  1. The cart is client-side. It is persisted to the browser's localStorage under ecommerce-storage. Nothing is reserved, nothing is held, and clearing site data empties the cart.

  2. Checkout is one atomic request. POST /api/ecommerce/cart/checkout validates every line — product active, stock sufficient, discount valid and unused — before it moves a single coin. If any line fails, the whole checkout rolls back. A partial checkout is not possible.

  3. One order is created per product, not per cart. A three-product cart produces three order rows. Shipping is charged once across the whole checkout, not once per order.

  4. The buyer's wallet is debited. Lines are grouped by wallet type and currency; each group's wallet is locked and its aggregated total checked before any debit. A buyer with no wallet in a product's currency gets Insufficient balance in <CURRENCY> wallet.

  5. The money is split three ways. The discounted subtotal is credited to the Super Admin wallet as store revenue. Shipping and tax are credited separately as a pass-through, deliberately not recorded as profit — you still owe the carrier and the tax authority.

  6. Status is decided by product type. DOWNLOADABLE orders are created COMPLETED. PHYSICAL orders are created PENDING and wait for you.

  7. Everything after the commit is best-effort. The confirmation email, the in-app notification and affiliate rewards run outside the transaction. A mail failure never un-sells an order.

Cancelling or rejecting an order reverses all of that: the platform's revenue is taken back, the shipping and tax pass-through is taken back, the buyer is credited the full amount they were debited, and physical stock goes back on the shelf — in one transaction, with every leg keyed so a retry cannot pay twice.

The two product types

PHYSICAL DOWNLOADABLE
Stock tracked Yes — checkout refuses below the ordered quantity No
Initial order status PENDING COMPLETED
Shipping charged Yes, if shipping is enabled Never
Tax charged Yes, if tax is enabled Yes, if tax is enabled
Fulfilment You mark it complete, optionally attach a shipment You attach a key or file per order item
Customer sees Order tracking timeline A download panel on the order

Where things live

Surface Path
Storefront /ecommerce
Product catalogue /ecommerce/product, /ecommerce/product/<slug>
Categories /ecommerce/category, /ecommerce/category/<slug>
Cart and checkout /ecommerce/cart, /ecommerce/checkout
Customer orders /ecommerce/order, /ecommerce/order/<id>
Customer shipments /ecommerce/shipping
Wishlist /ecommerce/wishlist
Admin dashboard /admin/ecommerce
Admin catalogue /admin/ecommerce/product, /admin/ecommerce/category, /admin/ecommerce/review, /admin/ecommerce/wishlist
Admin sales /admin/ecommerce/order, /admin/ecommerce/discount, /admin/ecommerce/shipping
Admin settings /admin/ecommerce/settings

What it does not do

Knowing the ceiling saves you a redesign later. None of the following exists, and no setting turns it on:

  • No card or gateway checkout. Buyers spend an existing wallet balance.
  • No product variants. One row is one price and one stock number. Size and colour need separate products.
  • No tax by jurisdiction. One flat percentage applies to the whole store.
  • No shipping zones, weights or bands. One flat amount per checkout.
  • No carrier integration. Shipment records are typed in by hand; the load ID and transporter are free text.
  • No automatic digital fulfilment. A downloadable order completes and pays you, but nothing is attached to it until an operator does it. See Digital delivery — this is the single most common support ticket on a new store.
  • No multi-image galleries. One image per product, one per category.
  • No partial refunds. Cancelling an order refunds the whole thing.
  • No server-side cart. It is browser storage; it does not follow the customer to another device.

Where to start

Install

Activate the licence, enable the extension, grant the permissions and confirm the storefront answers before you type a single product.

Catalogue

Categories, products, images, currencies and wallet types, inventory, reviews and wishlists.

Orders

The status machine, what a cancel actually moves, refunds, deletes and the emails your customers receive.

Digital delivery

Licence keys, download links, the file streamer, and why a paid digital order can arrive empty.

Shipping

The flat fee, shipment records, assigning them to orders, and the tracking timeline the buyer sees.

Discounts

Codes, the three discount shapes, per-product scope, usage limits and the fields the admin form does not expose.

Behind those sit Store settings — every setting key the store reads, including three that are displayed but wired to nothing — and the API and permissions reference. When something breaks, Troubleshooting lists the failures worth knowing in advance.