- An ecommerce dashboard can tell a buyer how much they ordered.
- Those two numbers are rarely the same.
- An order may still be a draft. It may have been cancelled.
- On a property-procurement marketplace built with Medusa, we turned that ambiguity into a dedicated funding report.
The client problem
An ecommerce dashboard can tell a buyer how much they ordered. Finance is asking a different question: how much money will each property need during the next funding period?
Those two numbers are rarely the same.
An order may still be a draft. It may have been cancelled. Its invoice may not have been checked. It may already have been paid through another path. Tax may have been confirmed by the supplier after checkout. And a regional manager asking for one property must not receive the cash requirement for every building in the organisation.
On a property-procurement marketplace built with Medusa, we turned that ambiguity into a dedicated funding report. It starts from the purchasing lifecycle, selects the obligations that are genuinely ready to fund, calculates their latest value, and exposes them at either organisation or property level according to the caller's role.
The result is not another sales report. It is a bridge between commerce activity and a finance decision.
The client problem: checkout totals do not answer a treasury question
Commerce systems are very good at recording what happened at checkout. They know the order, the products, the quantity and a total. A property business needs another layer of meaning.
Finance needs to know which purchases have reached a stage where money should be reserved. It needs a reporting window. It needs to separate buildings, suppliers and general-ledger accounts. It needs to open the underlying orders when a number looks surprising. Most importantly, it needs confidence that an order is not counted twice after payment.
A spreadsheet can approximate this process. Someone exports orders, removes drafts, looks for invoice status, checks a payment column, copies totals into property tabs and sends a workbook around. That works until states change between exports, two people use different filters or one recipient sees properties outside their remit.
The real requirement was therefore not “add a total to the dashboard”. It was: give finance one governed population of upcoming obligations, keep it connected to the orders that created it and preserve property access throughout the report.
Medusa supplied the order lifecycle and extensible backend. We added the accounting meaning the client needed.
First define what “needs funding” means
The hardest part of a funding report is not addition. It is eligibility.
We start by excluding records that cannot represent a current obligation: deleted links, deleted orders, draft orders, cancelled orders and completed orders. We then limit the population to the reporting period.
An order must also have crossed a business checkpoint. In this implementation, that means the buyer invoice has been validated or the accounting workflow has moved into one of the accepted states: reviewed, awaiting or exported. An unreviewed basket does not become a treasury requirement merely because it exists in the order table.
Finally, the report removes orders whose buyer-side payment has already been recorded. It checks both the order metadata and linked split-payment records for paid or captured states.
That definition matters because every report has an implicit contract. If “open” means one thing to procurement and another to finance, the total may look precise while answering no useful question.
We encoded the contract in the query itself: validated enough to fund, not yet paid, still active, and inside the chosen period.
Use the latest commercial value, not an old snapshot
Orders can evolve after their first creation. A summary may be versioned as adjustments are made, and supplier tax can arrive through a separate part of the workflow.
For each eligible order, the funding query reads the latest order summary rather than assuming the first total is still authoritative. It then adds vendor tax only when the order explicitly marks that tax as set and provides a positive tax amount.
This is a small implementation detail with a large business consequence. A funding report built from stale totals asks finance to reserve the wrong amount. A report that always adds a tax field can count incomplete or irrelevant metadata. A report that never adds it can understate an accepted supplier obligation.
The calculation therefore follows the state already established by the purchasing and invoice workflow. It does not invent a parallel total.
The report currency is explicit, and the underlying orders remain available next to the summary. Finance can move from the aggregate back to the commercial record instead of treating a number as an unexplained fact.
Let the organisation define the reporting period
“This month's funding” sounds obvious until different organisations close their books on different dates.
The platform first looks for a configured spend date range in the organisation settings. When it exists, that range defines the funding period. When it does not, the report falls back to the current calendar month in UTC.
The query treats the visible end date as inclusive by converting it into an exclusive next-day database boundary. That avoids a common reporting bug in which orders from the final day disappear because timestamps are compared with midnight at the start of that day.
The response returns the chosen start, end and source. The interface can therefore tell finance whether it is showing an organisation-defined cycle or the default month.
This makes the report predictable. A number without its period is not a funding requirement; it is just a total. By making period selection part of the response contract, exports, on-screen summaries and conversations can all refer to the same window.
Scope before loading a single order
The second major question is not how much to show, but whose money the caller is allowed to see.
The Store route begins from authenticated customer and organisation context. It accepts only roles that have a reason to use funding information. Master and accountant users can request an organisation-wide view. They may also select one property, but that property must belong to the authenticated organisation.
Manager, supervisor and buyer roles operate differently. They require an active property context connected to the same organisation, and the backend checks that the authenticated customer is linked to that property. A property identifier in the URL is never enough by itself.
Only after this decision does the report choose its link table and query orders. Organisation scope follows organisation-to-order links; property scope follows property-to-order links.
This ordering is deliberate. We do not load the whole portfolio and hide rows in the browser. The access boundary determines the database population from the beginning.
For a multi-property client, that is what turns a convenient dashboard into a trustworthy operational tool.
One summary, several ways to investigate it
A useful funding report needs more than one headline number.
The response contains the number of eligible orders and the total funding amount. It also returns the current page of orders so a user can inspect the transactions behind the figure. A search box can narrow that page by order number without changing the broader summary population.
The same eligible-order definition feeds breakdowns by GL code and vendor. Finance can see not only how much cash is required, but where the requirement comes from: which expense categories are consuming it and which suppliers are due to receive it.
These are not three unrelated reports assembled on the frontend. They are different views over the same governed funding population. That reduces the chance that the headline says one thing while a vendor chart quietly applies another status rule.
The page can switch between property and organisation views when the user's role allows it, paginate the supporting orders and export the result to CSV or XLSX. The interaction stays familiar, while the backend retains control of meaning and scope.
Translate quantity allocations into accounting amounts
Property procurement often splits a purchased line across general-ledger codes. The commerce primitive in this project stores quantity portions against a line item, unit and GL account.
Finance, however, needs money.
The funding report reads the current order-item version, combines unit price with the allocated quantities and derives monetary weights. If a line is split between two GL codes, its spend follows those weights. Rounding remainders are reconciled deterministically so the breakdown returns to the order amount rather than drifting by a few cents.
This distinction is important. We do not pretend the cart stored arbitrary accounting amounts when it actually stored quantity allocations. The monetary view is a downstream interpretation of the purchasing decision.
That preserves a clean chain of explanation: the buyer allocated physical quantity, the order retained that structure, and the reporting layer translated it into finance values using the current line price.
The GL breakdown can then show spend, contributing orders and line-level quantities without disconnecting accounting from the original purchase.
Keep vendor totals tied to supplier identity
Funding also has a supplier dimension. Finance may need to understand concentration, prepare payments or investigate why one vendor accounts for a large share of the current requirement.
The vendor breakdown groups eligible spend by the seller identity connected to each order. It returns the vendor name and the supporting order contributions rather than only a label and a total.
That traceability is valuable when two suppliers sell similar products or when an order contains a tax adjustment. A finance user can follow the amount back to the exact orders and lines that produced it.
The report does not replace an accounts-payable ledger. It prepares the operational view that sits before funding and payment: these validated purchases are still unpaid, these properties own them, these GL categories explain them, and these vendors are involved.
By keeping that view inside the commerce platform, procurement and finance discuss the same records instead of reconciling separate exports with different identifiers.
Design search and pagination so they do not distort the total
Search creates a subtle reporting choice. If a user searches for order 123, should the headline become the value of that one match or remain the full period requirement?
In this implementation, the paginated order list and match count follow the search term, while the funding summary and breakdowns continue to describe the full scoped period. The interface can therefore use search as an investigation tool without silently redefining the organisation's cash requirement.
That behaviour must be communicated in the UI. A user should be able to distinguish “one matching order” from “the total funding need for this property”. Otherwise a perfectly correct backend can still create a misleading finance experience.
Pagination follows the same principle. It limits how many order records are returned to the browser; it does not calculate the headline from only the visible page.
The route bounds page size and normalises order-number search input. Operational convenience does not get to rewrite the report contract.
Why this belonged inside the Medusa architecture
The client did not need a disconnected business-intelligence project. The necessary facts already lived across commerce: current order summaries, invoice validation, accounting status, payment links, property ownership, line allocations and supplier identity.
Medusa was the right foundation because those domains could be extended and queried together. We added organisation and property relationships, accounting metadata and reporting logic without rebuilding the order engine.
The result demonstrates the architectural value of an extensible commerce platform. The answer to a specialised business requirement was not to force the client into a generic sales dashboard. It was to preserve Medusa as the transactional foundation and build the finance capability on top of its real lifecycle.
The custom route also creates one contract for the storefront, exports and future operational tools. Access checks and eligibility rules stay server-side rather than being copied into every consumer.
Architecture becomes useful when it lets the platform speak the client's business language.
The release checklist we use for funding visibility
Before a funding report reaches finance, we ask:
- Which exact order states represent an upcoming obligation?
- What business event proves the invoice is ready to fund?
- How is an already-paid order excluded?
- Which version of the order total is authoritative?
- When is supplier tax included?
- Who defines the reporting period?
- Is the final date treated inclusively?
- Which roles may see the whole organisation?
- How is a selected property checked against that organisation?
- Do property-level users have an explicit relationship to the property?
- Are totals computed from the full scope rather than the visible page?
- Does search narrow investigation without silently changing the headline?
- Do GL and vendor breakdowns use the same eligible population?
- Can every aggregate be traced back to contributing orders?
- Do CSV and spreadsheet exports preserve the visible period and scope?
These questions make the report useful to finance and safe for a multi-property organisation.
The broader lesson
Funding visibility is not a charting problem. It is a domain-modelling problem.
The platform must decide when a purchase becomes a credible obligation, when it stops being one, which value is current, how allocations become accounting amounts and which part of the organisation the caller may inspect.
For this client, we encoded those decisions next to the Medusa order lifecycle. Eligible unpaid orders form one governed population. Organisation and property scope are resolved before loading data. The same population drives the total, GL breakdown, vendor breakdown and supporting order list.
That gives finance an answer it can act on without asking procurement to rebuild the truth in a workbook.
The feature is specific to property purchasing, but the principle travels well: when a business asks for “the number”, build the state, scope and explanation that make the number meaningful.