- The client was not trying to launch another online shop.
- It needed property organisations to find supplies across many vendors, buy for the correct site, route exceptional spend through approval, receive goods from different fulfilment locations,
- The raw ingredients looked familiar: products, prices, carts, orders and payments.
- We chose Medusa as the commerce engine because we knew we could keep its standard transactional primitives and extend it around those client problems.
The client problem
The client was not trying to launch another online shop.
It needed property organisations to find supplies across many vendors, buy for the correct site, route exceptional spend through approval, receive goods from different fulfilment locations, reconcile supplier invoices and carry the financial result into property accounting.
The raw ingredients looked familiar: products, prices, carts, orders and payments. The operating reality was not. Supplier catalogues could contain enormous files and inconsistent identifiers. One customer organisation could manage hundreds of properties. The person selecting a product might not be allowed to approve the purchase. A single checkout could create work for several sellers and stock locations. Purchase-order terms did not behave like card payments. The invoice arriving later could disagree with both the order and the goods received.
We chose Medusa as the commerce engine because we knew we could keep its standard transactional primitives and extend it around those client problems. The result became a procurement platform for property operations: one system connecting catalogue ingestion, marketplace discovery, organisational governance, multi-vendor fulfilment, documents, invoice control and accounting integration.
This case study explains the transformation through the business journey. The individual implementation guides go deeper into each capability; the story here is how the parts became one coherent product.
The brief: make fragmented property purchasing operable
Property supply purchasing is rarely one clean funnel from product page to card payment.
A maintenance employee notices a need at a specific building. They may know the supplier SKU but not the marketplace product name. A manager needs to understand whether the purchase fits the property's budget and whether approval is required. The chosen vendor may fulfil from one of several branches. The organisation may buy on account using a purchase order. After delivery, finance needs an invoice that matches what was ordered and what actually arrived. Finally, the transaction must be represented in the property accounting system with the right general-ledger and unit allocations.
Before the platform can support that journey, it must make four kinds of context explicit:
- who is acting and which organisation role they hold;
- where the purchase belongs, down to the active property;
- who sells and fulfils each part of the order;
- which commercial and accounting rules apply to that relationship.
A conventional storefront can hide these questions until checkout. A procurement platform cannot. They influence search visibility, price lists, approved suppliers, stock location, delivery, approvals, credit and accounting from the beginning.
Our architecture therefore did not begin with a redesigned homepage. It began by identifying the business objects and transitions that had to remain true across the whole journey.
Why Medusa was an architecture choice, not just a technology preference
Medusa already gave the project robust commerce foundations: products and variants, sellers, inventory, carts, orders, promotions, workflows, modules, events and application surfaces for shoppers and operators.
It did not automatically know what a property is, how an organisation selects approved vendors, when a building has supplier credit, how a maintenance list moves from draft to ready, what an accounts-payable reviewer should do with three invoice PDFs or how a property accounting system expects an AP bill.
That was a reason to choose an extensible engine, not a reason to reject it.
We could preserve standard commerce behaviour where the problem was standard and introduce first-class modules where the client's operating model differed. Property context became a real input to commerce. Approval decisions became durable workflow state. Catalogue imports became observable jobs. Supplier invoices became reviewable sources. Accounting exports became an explicit translation contract.
The alternative would have been a collection of storefront scripts and external spreadsheets pretending to be one product. Medusa allowed the customised behaviour to participate in the same product, cart and order lifecycle as the core transaction.
Capability one: absorb supplier catalogues without taking commerce down
The marketplace could not exist until it could ingest the catalogues that professional buyers already used.
Those files were not small hand-curated product sheets. They could contain vast numbers of rows, multiple record shapes, supplier-specific identifiers, variants, prices, inventory and media. A request that attempted to parse and write everything before returning would time out, consume too much memory and leave operators with no idea whether a failed import had changed anything.
We built a staged import system around bounded work. The upload and import record establish durable identity first. Parsing discovers the file's actual structure instead of assuming that every supplier uses the same delimiter, encoding or header row. Mapping converts supplier fields into a canonical product graph. Validation happens before expensive mutation. Creation and update proceed in chunks with persisted progress and explicit outcomes.
The operator can distinguish created, updated, unchanged and rejected records. That is far more useful than a green banner saying “import complete”. A no-op is meaningful evidence that the incoming product already matches the catalogue. A rejected row needs a reason that can be corrected without rerunning an opaque million-row request.
When an execution stops, a stable operation identity and progress record let the system determine what remains instead of starting from zero blindly. The platform can resume bounded work and reconcile projections such as search visibility after interrupted inventory updates.
The detailed architecture is in How we kept a large supplier catalogue import from taking Medusa down, while The supplier import has been running for twenty minutes. Is it working, stuck or safe to resume? focuses on the operator journey.
Existing price lists needed their own contract
Some organisations already had negotiated supplier price sheets. Those values could not simply overwrite Medusa's standard catalogue prices, because price meaning depends on supplier, organisation, effective period and commercial agreement.
We modelled imported price lists as a distinct business input and reconciled their rows with products rather than treating the spreadsheet as the catalogue itself. The source file, mapping and import outcome remain inspectable. Updates can apply deltas without recreating products that already exist.
That distinction preserves two useful truths: Medusa owns the current commerce representation, while the supplier file remains evidence of the commercial input that produced it.
See A supplier price list should not rewrite your catalogue: how we imported it in Medusa and A supplier sends a catalogue update. How do you change 8,000 products without rebuilding them?.
Capability two: make an enormous catalogue searchable in the language buyers use
Importing products does not make them discoverable.
Property buyers frequently describe a problem rather than a catalogue noun: a replacement part for a particular appliance, a compliant fixture for a unit turnover, or the cheapest suitable item that can arrive within a deadline. Supplier descriptions may use abbreviations, manufacturer terminology or inconsistent taxonomy.
We built Elasticsearch as a derived marketplace read model assembled from several Medusa domains. It combines product and variant identity, supplier context, taxonomy, specifications, visibility, delivery options and the commercial information needed for discovery.
The index is not a second source of truth. Medusa and the marketplace modules own the underlying facts; indexing creates a queryable projection. Shared builders and reconciliation paths keep full reindex, incremental updates and repair jobs aligned.
On top of that projection, search can combine lexical precision, hybrid retrieval and semantic signals. A constrained planner translates natural-language intent into a bounded query plan. Hard commercial filters remain deterministic, while model assistance helps interpret what the buyer means.
This separation avoids a common AI mistake: asking a model to invent the catalogue answer. Retrieval finds eligible candidates first. The language layer helps organise the request and explain the result. Price, seller visibility and delivery constraints remain grounded in the marketplace data.
Read When buyers describe a problem instead of a product: building AI procurement search on Medusa and “Find the cheapest dishwasher I can receive within two days.” How should Medusa search?.
Comparison became a live decision surface
Once buyers found several plausible products, they needed to compare and share the shortlist. We limited the decision set to four products and stored only their identities in the URL.
When another person opens that link, the backend reconstructs current facts under their active context. Price, stock, visibility and delivery are not frozen inside the link. Unknown specifications remain unknown, and the interface refuses to declare a lowest comparable price when units differ.
The result supports a human purchasing conversation without turning an old browser state into a commercial promise.
Capability three: model the customer as an organisation of properties
A consumer account is usually one person with addresses. The client needed companies, associations and property-management organisations whose people act across different sites.
We introduced a hierarchy in which people belong to an organisation but operate within explicit property context. A user may be a master across the organisation, a manager for selected sites or a shopper at one property. The active property propagates through catalogue, cart and procurement routes as a business input.
This is not visual filtering. Server-side guards resolve the actor's allowed scope and reject resources outside it. A guessed property or cart identifier cannot widen access.
The same model supports large portfolio onboarding and everyday switching. The interface helps an authorised user move between properties, while the backend repeats the boundary on every consequential operation.
One customer account, hundreds of sites: modelling a property business in Medusa explains the domain, and the dedicated active-property guide covers how that context reaches storefront operations.
Shared buying lists moved intent between roles
The person who discovers a need is not always the person who purchases it. We extended Medusa wishlists into multiple named lists owned by a property.
Contributors can add exact variants, quantities and notes. Revisions prevent one person's stale edit from silently overwriting another's work. A draft becomes a precise ready revision, and the buyer can copy that revision into the correct property cart. The transfer rechecks current product visibility and uses a durable import record to prevent retries from duplicating quantities.
The familiar idea of a wishlist becomes a lightweight procurement document: collaborative before checkout, traceable afterwards and still connected to Medusa's live products and carts.
Capability four: govern spend without queuing every purchase
Approvals are valuable when they focus attention. They become friction when every routine order waits for a manager.
We built progressive approval routing around the reasons a purchase needs intervention. Amount can matter, but so can property budget, role, supplier relationship and the state of the request. Orders that satisfy policy continue; exceptions create an approval case for the appropriate property-scoped decision makers.
The approval record keeps the revision being judged. If a buyer changes a rejected request and resubmits it, the new proposal does not erase the previous decision. Concurrent decisions are checked against current state so a late approver cannot overwrite a newer outcome casually.
This gives the organisation both speed and governance. Ordinary purchasing remains ordinary. Exceptional spend produces a durable explanation of who decided what and against which version.
Read How we added purchase approvals without turning every Medusa order into a queue and The purchase was rejected. Why should the buyer have to start again?.
Approved vendors and property credit completed the policy
An organisation may be allowed to buy only from selected suppliers. Even then, purchase-order credit can differ property by property.
We represented approved-vendor selection separately from supplier credit. The first controls assortment eligibility for the organisation. The second records whether a particular property has the commercial terms needed to place a purchase-order transaction with that supplier.
This prevents one broad relationship from granting more authority than intended. A company can approve a vendor for discovery while requiring a credit application before one building uses account terms.
Capability five: keep a multi-vendor checkout coherent
A buyer wants one clear purchasing journey. Behind it, products may belong to several sellers, ship from different stock locations and follow different delivery rules.
We modelled seller and location topology explicitly. Each supplier can own stores, warehouses or distribution centres. Inventory and fulfilment capability attach to those locations. Property geography and supplier delivery zones determine which options are relevant.
Country, state, city, postal-code and radius rules let the platform answer a concrete question: can this supplier location serve this property? Distance calculation can rank eligible stock locations without treating straight-line proximity as the only delivery rule.
The cart must retain enough context to keep seller lines, delivery selections and property ownership coherent as it becomes an order. A single customer action can then produce the correct seller-facing work without pretending all lines come from one warehouse.
One buyer checkout, several sellers and sites: keeping the Medusa journey coherent tells the full journey. The supplier has stock. But which site can actually fulfil the Medusa order? and The supplier delivers to Houston, but not every address in Texas. How should Medusa decide? go deeper into topology and geography.
Suppliers could receive orders in their own systems
Not every supplier wants another portal queue. We added seller-specific outbound webhook configurations with custom endpoints and headers, dedicated secrets, signed event bodies, sample dispatch and delivery diagnostics.
The order determines the supplier; the caller does not choose a recipient. A stable supplier-facing payload translates Medusa commerce facts into the receiving system's contract. Operators can test the integration before activation and rotate its signing secret later.
This creates a controlled bridge from marketplace acceptance to supplier operations without making the remote endpoint part of Medusa's database transaction.
Capability six: treat purchase orders as terms, not fake card payments
For approved property purchasing, “payment” can mean that the supplier extends account terms and expects a purchase-order document. No card is captured at checkout.
We extended the Medusa journey with a purchase-order payment type governed by customer, property and supplier eligibility. The resulting order retains the information needed to generate a procurement document: parties, lines, totals, delivery, allocations and references.
The document is generated from canonical order data rather than reconstructed from the browser. It remains a representation of the transaction, not a competing order record.
A purchase order is not a card payment: adding account terms to Medusa checkout explains the commercial state model, while The order was placed. Can everyone now produce the right procurement document? covers document production.
Quotes could become orders without losing the supplier decision
Some requests need a supplier response before purchase. A quote can change price, quantity, availability or fulfilment terms.
We kept quote negotiation distinct from the final order and added an explicit conversion. The accepted quote supplies the commercial proposal, but order creation still uses Medusa's order lifecycle and validates the current transition. The platform does not treat a PDF or message as the transaction itself.
That gives buyers and suppliers a shared negotiation object while preserving one authoritative order afterwards.
Capability seven: reconcile invoice, order and receipt
The order describes what the buyer intended. The receipt describes what arrived. The supplier invoice describes what the vendor wants paid. Accounts payable must compare all three.
We modelled each supplier PDF as a durable source with review and extraction state. Email and order-page uploads enter the same controlled process. Several files can belong to one invoice case, and duplicate or superseded sources remain traceable.
A specialised extraction service can read invoice numbers, order references, totals and line items, but it cannot approve payment. The platform applies seller and order eligibility rules to any proposed match, preserves confidence and leaves acceptance to the review workflow.
Reconciliation then compares ordered, received and invoiced facts. Unknown line mappings become human tasks rather than guessed product identities. Differences can be classified and resolved with history.
The order says one thing. The goods receipt says another. Should Medusa release the invoice? covers the three-way control. An invoice arrived by email. How can AI read it without deciding who gets paid? explains the AI authority boundary.
Capability eight: carry the purchase into property accounting
The commerce order total is not yet an accounting entry. Finance needs merchandise, shipping, taxes and discounts represented deliberately. One order line may need allocation across general-ledger accounts or property units.
We allowed those allocations to travel with the procurement object rather than being recreated at the end. Export logic translates reviewed Medusa orders into balanced accounting rows and preserves the relationship back to commerce.
For the property accounting integration, AP bill synchronisation uses an explicit external mapping and lifecycle. The integration records what was sent and how the remote system responded. It does not make the accounting platform and Medusa co-own every field.
See One order line, three properties: carrying GL allocations through Medusa, The Medusa order total is correct. Why can finance still not post it?, and When a Medusa purchase becomes a RealPage AP bill: keeping commerce and accounting in sync.
Capability nine: give operators one place to understand the system
A platform this rich cannot be operated through raw logs and database queries.
We built back-office surfaces for the people responsible for catalogue imports, workflow execution, seller organisations, approvals, delivery, invoices and integrations. The key design was not a dashboard full of counters. It was a set of business-readable queues and timelines.
The operator Control Center gathers problems that need action: failed or stale work, unmatched data, interrupted imports and integration exceptions. Parent and child workflows can be read as one operation tree. Stable transaction identities connect retries and sub-operations to the original business task.
Supplier and buyer teams have their own application surfaces and APIs. Admin, vendor and store concerns are separated so a seller interface does not inherit platform-wide administrator authority. Tenant checks live on the server, not only in navigation.
The result is a platform that can explain itself. An operator can see what the system attempted, what outcome occurred and which action is available next.
Your marketplace does not need more alerts. It needs an operator Control Center and One Medusa backend, three applications: keeping buyers, sellers and operators in their own lane cover those operational and security boundaries.
What the project demonstrates about composable commerce
The strongest argument for composable commerce is not that engineers can replace every component. It is that a business can keep proven transaction primitives while expressing the operating rules that make it distinctive.
In this project, Medusa remained recognisably Medusa. Products became variants in a catalogue. Carts became orders. Workflows coordinated mutations. Modules owned domain state. Events connected bounded effects.
Around those foundations, we added the capabilities the client actually needed:
- industrial-scale supplier catalogue ingestion;
- semantic and constrained procurement discovery;
- organisation and property scope;
- collaborative buying lists;
- approval and budget governance;
- approved vendors and property-level credit;
- multi-seller, multi-location fulfilment;
- purchase-order checkout and document generation;
- supplier invoice extraction and three-way reconciliation;
- GL allocation and property accounting integration;
- operator control, tenant isolation and integration observability.
None of those capabilities was valuable because it contained more code. Each one removed a concrete obstacle between a property need and an accountable purchase.
The architecture method underneath the product
Although the story begins with client problems, several repeatable decisions made the solutions work together.
Name the business object. A property, approval case, shopping-list revision, invoice source or accounting allocation deserves durable identity when the organisation will need to discuss it later.
Separate authority from projection. Medusa and specialised modules own commerce state. Elasticsearch, AI summaries, PDFs and dashboards make that state easier to find or understand; they do not silently become new sources of truth.
Carry scope into every operation. Organisation membership, active property and seller ownership are resolved server-side wherever they affect visibility or mutation.
Turn long work into a lifecycle. Imports, AI jobs and integrations have queued, running, completed and failed states with progress and provenance. The browser does not have to keep one request alive to prove that work exists.
Make ambiguity visible. An unmatched SKU, several candidate products, an unknown delivery estimate or an invoice difference becomes an explicit review state rather than a fabricated answer.
Design the operator path with the feature. If a workflow can fail, the product needs a way to find, understand and safely retry or resolve it.
These are architecture choices, but they matter because they produce a platform people can operate. We do not need to announce “clean architecture” in every section. The evidence appears in the way each client problem reaches a dependable outcome.
A platform, not a pile of custom features
The risk in a highly customised commerce project is ending with dozens of unrelated extensions. The way out is to reuse domain boundaries and context across capabilities.
Property scope affects search, lists, carts, approvals, delivery, credit and accounting. Seller identity affects catalogue ingestion, price lists, fulfilment, webhooks and invoices. Order identity connects quote conversion, purchase orders, receipts, invoice review and AP bills. Workflow identity connects long-running imports and operational control.
Because those concepts are shared, each new capability strengthens the platform instead of creating another island. A supplier catalogue imported once can be searched, compared, placed on a property list, approved, fulfilled, reconciled and accounted for through one connected model.
That is the transformation this project delivered: not a storefront with an unusually long feature list, but a commerce foundation extended into the client's procurement operating system.
The result WeAreSouk can reproduce
This case does not suggest that every Medusa project needs the same modules. Another client may not manage properties, use purchase-order terms or connect to the same accounting platform.
The reusable expertise is our ability to find where the client's business stops matching standard commerce, choose a platform that can absorb the difference and build the missing capability without losing operational coherence.
For a commerce leader, the starting questions are practical:
- Which work still happens in spreadsheets, email and copied data?
- Which people, sites and suppliers participate in one purchase?
- Where does an exception require human authority?
- Which downstream systems need the transaction, and which facts do they own?
- When automation fails, can an operator understand and recover it?
If those questions reveal that a standard storefront is forcing the business into the wrong shape, WeAreSouk can map the procurement journey and design the Medusa extensions that make it operable.
What this project demonstrates
This project shows what becomes possible when an extensible commerce engine is treated as a foundation rather than a constraint. Medusa supplied the core commerce lifecycle; we added the property, supplier, approval, fulfilment, invoice and accounting capabilities the client actually needed. The result is a coherent procurement platform in which each business problem has a deliberate place, while operators retain a clear view of the work moving through the system.