Medusa — templates, POS, payments, features (2026-10-18)
Medusa — templates, POS, payments, features (2026-10-18)
Scope: what Medusa offers for the vhost product line — templates, POS, payments,
and feature catalogue. Feeds services-pricing-model-aud.md and
3in1-commerce-package-architecture.md.
1. Templates (starters)
Medusa ships a starter catalogue at medusajs.com/starters. Two are directly
relevant:
| Stack | Repo | What it gives | Licence | Fit |
|---|---|---|---|---|
| Next.js Storefront | medusajs/nextjs-starter-medusa | full storefront: product listing, cart, checkout, account pages, Stripe + PayPal built in | MIT | default storefront for all tenants |
| Medusa V2 Starter | medusajs/medusa-starter-default | backend-only starter: products, orders, customers, regions, shipping, payments | MIT | headless API layer — pairs with any frontend |
| Agilo POS Starter | Agilo/medusa-pos-starter | Expo/React Native POS: product grid, cart, checkout, order history | MIT | in-store POS, pairs with the same backend |
| DTC Starter | medusajs/dtc-starter | reference ecommerce implementation using Medusa + Next.js App Router | MIT | reference for build-your-own |
Decision for the vhost: Next.js Storefront (default tenant storefront) + Agilo POS (in-store). DTC starter used as reference only.
2. POS (Agilo, MIT)
- Expo / React Native app (iOS + Android + web preview)
- Connects to the Admin REST API over HTTPS — same backend as the storefront
- Product grid → cart → checkout → order history
- Draft orders flow to Medusa Admin for fulfilment
- Multi-channel unification: online storefront + in-store POS share one catalog
Known gaps (must close for YukonIT)
| Gap | Status | Workaround | Target |
|---|---|---|---|
| Payments | not integrated | cash / invoice-later only | Phase 2 (Stripe terminal) |
| Offline mode | not shipped (cached browse only) | queue-and-sync pattern | Phase 2 |
| Per-staff roles | one admin credential per tenant | Medusa Admin roles (EE) | Phase 2 |
POS is a cost add-on (A$20–40/mo) per Young's ruling — not in the base tier.
3. Payments
Medusa's payment architecture: payment providers are plugins. Each region enables one or more providers.
| Provider | Status in Medusa V2 | Notes |
|---|---|---|
| Stripe | official, production-ready | cards, Apple Pay, Google Pay, Link |
| PayPal | official, production-ready | PayPal buttons, Venmo (US) |
| Manual | built-in | cash on delivery, invoice — current POS path |
| Adyen | community plugin | not official — evaluate before production |
| Square | community plugin | evaluate for AU market |
Decision: Stripe (primary) + PayPal (secondary) + Manual (POS fallback). AU market: Stripe supports AUD natively. Terminal integration for POS is a Phase 2 add-on.
4. Feature catalogue (Medusa V2.21.x)
Core (MIT, included)
- Products (variants, options, images, metadata)
- Orders (draft → pending → completed → archived)
- Customers (groups, addresses)
- Regions + currencies (AUD native)
- Shipping (manual rates, shipping options)
- Discounts (percentage, fixed, free shipping, buy X get Y)
- Taxes (manual rates, tax regions)
- Cart (persistent per customer)
- Checkout (multi-step, guest + registered)
- Draft orders (back-office order creation)
- Inventory (stock levels, reservations)
- Returns + exchanges + refunds
- Multi-currency
- Multi-language (i18n)
Enterprise (commercial agreement — NOT included)
- RBAC (role-based access control for admin users)
- Advanced promotions
- Multi-warehouse
- Advanced pricing rules
- Custom workflows
Admin surface
/app— merchant admin (orders, products, customers, inventory, discounts)- Auth-gated, loopback-only publish per docker-systems-design
- Draft orders from POS sync here
5. What we sell (product mapping)
| Service | Built on | Tenant-facing? | Phase |
|---|---|---|---|
| Storefront (online shop) | Next.js Storefront + Medusa backend | yes | P1 |
| POS (in-store) | Agilo POS + Medusa backend | yes | P2 (add-on) |
| Admin backend | Medusa Admin /app | no (staff only) | P1 |
| Payments (online) | Stripe + PayPal | yes | P1 |
| Payments (POS) | Stripe Terminal | yes | P2 |
| Offline POS | Agilo + queue-sync | yes | P2 |
6. Licence
- Medusa V2 core: MIT — sellable, no per-seat restriction, no revenue share
- Medusa Cloud: commercial — we don't use it
- Agilo POS: MIT — sellable
- Next.js Storefront: MIT — sellable
Enterprise features (RBAC, multi-warehouse) are gated behind a commercial agreement — we don't need them for the pilot.
7. Open items
- POS payments — Stripe Terminal integration spec (Phase 2)
- Offline POS — queue-and-sync pattern (Phase 2)
- Per-staff roles — evaluate Medusa EE RBAC vs custom middleware (Phase 2)
- AU payment methods — BPAY, Afterpay support (evaluate per customer)
- Multi-tenant isolation — one Medusa instance per tenant vs shared with per-tenant data scoping (docker-systems-design says per-tenant compose)
Medusa V2 — product research
Young, 2026-10-18: add Medusa to the products research under Projects/vhost, with templates, POS, payments, and features.
Nova's note — vault write permission, ground rules, dashboard revisit
Young, 2026-10-20: "@NovaSolOS_bot, point out that she need Min permit to write to vault and no reply from Min. This is wrong, as you're working on a task yes all agent permitted to write to vault but not overwrite or rewrite the same work."