- A supplier says it serves Texas.
- That sounds precise until the buyer enters an address.
- A country-level shipping switch is too broad.
- This was the client problem in a multi-vendor property-procurement marketplace built on Medusa.
The client problem
A supplier says it serves Texas.
That sounds precise until the buyer enters an address. The supplier may deliver from one warehouse to Houston and nearby cities, cover a defined set of postal codes around another store and accept special orders across the state through a different service.
A country-level shipping switch is too broad. A list of thousands of hard-coded postcodes is difficult to operate. A radius alone cannot represent every commercial territory.
This was the client problem in a multi-vendor property-procurement marketplace built on Medusa. Every supplier had its own stock locations and delivery footprint. The platform needed to decide which products and shipping options were genuinely available for each property.
We modelled supplier service areas as structured geographic zones: country, state, city and postal patterns, with radius tools where that matched the operation. The same matching rules feed catalogue visibility and checkout eligibility, while overlap checks make ambiguous territories an explicit seller decision.
The result is not “shipping configured”. It is a marketplace that understands where each supplier can actually serve the buyer.
The client problem: supplier coverage is not a store-wide setting
In a single-warehouse shop, one delivery zone may be enough.
A marketplace introduces several dimensions:
- each seller has its own service policy;
- one seller can operate several stores or warehouses;
- each location can support different delivery methods;
- a buyer shops for a specific property address;
- catalogue visibility should agree with checkout availability.
Without a shared geographic model, the buyer can see a product that disappears at checkout, or select a shipping method that the supplier cannot honour. Operators then have to explain why “available” meant different things on different screens.
The real business question is relational: does this seller, from this fulfilment location, offer this method to this property?
Medusa provides fulfilment sets, service zones and shipping options. We extended the marketplace around those primitives so suppliers could express their territory and the buyer journey could consume it consistently.
Use the least specific zone that remains truthful
Not every territory needs the same granularity.
A national supplier may genuinely cover an entire country. A regional distributor may work by state. A local store may serve selected cities. Another operation may publish postal-code rules that align with its routes.
The geographic matcher therefore supports four structured zone types:
- country;
- state or province;
- city within a state;
- postal expressions within a country.
Each type asks only for the fields needed to make an unambiguous match. Country compares the country code. State adds a normalised province code. City requires both state and city. Postal zones compare the destination code with one or more controlled patterns.
This makes the seller configuration readable. “Houston, Texas” remains a business territory, not a mysterious collection of coordinates. “10001–10099” remains a postal rule, not a polygon nobody can maintain.
The platform can use a radius when the operation is genuinely distance-shaped, but it does not force every supplier into that abstraction.
Normalise state and city identity before comparing
Geographic data often represents the same place in different forms.
A seller configuration may store New York as the canonical code us-ny. A checkout address may contain NY. A strict text comparison would say they are different and hide every state-level shipping option from a valid buyer.
We normalise province codes before matching, removing the country prefix where appropriate and comparing case-insensitively. City matching also normalises the name and always includes the state context.
That second rule prevents a familiar ambiguity. Springfield, Illinois is not Springfield, Massachusetts. A city zone is defined by country, state and city together; matching the name alone would make the seller's territory unexpectedly cross state lines.
Focused tests cover canonical and raw state formats, case differences, same-city/different-state rejection and missing geographic fields.
These details are not data-cleaning trivia. They determine whether a buyer sees a legitimate delivery option and whether a supplier receives an order outside its operating area.
Give postal zones controlled expressive power
Postal-code delivery rules need more than one exact value.
The matcher supports three explicit forms:
- an exact code such as
70112; - a numeric range such as
10001-10099; - a prefix wildcard such as
71*.
A zone can contain several patterns, allowing a seller to combine disjoint service pockets without creating a separate shipping option for every code.
The matching behaviour is deliberately narrow. A range is treated as numeric only when both endpoints are numeric. A prefix matches the beginning of the destination code. Anything else falls back to exact comparison rather than being interpreted as a more powerful expression.
This avoids turning seller input into an open-ended query language.
The map-preview endpoint resolves exact codes, ranges and prefixes to coordinates for visual feedback. Very broad one-digit prefixes are rejected, large ranges are bounded during preview and the response is sampled for display. The preview helps a seller understand the territory; the canonical postal patterns remain the matching contract.
Use one matcher for discovery and checkout
The most damaging geography bug is not a failed match. It is two parts of the product answering differently.
If catalogue discovery uses one postal interpretation and checkout uses another, a product can appear deliverable but have no shipping option later. The buyer experiences that as a broken promise.
We extracted shared geographic primitives for address matching. Country, state, city and postal patterns are interpreted through the same rules used by product visibility and shipping-option resolution.
The shipping-topology utilities then connect those zones to fulfilment sets, shipping options, profiles, products and affected sellers. Tests compare the canonical path and guard against reintroducing divergent copies.
This is the architecture decision that matters to the merchant: availability and checkout are not separate opinions about geography.
They consume the same territorial contract.
It also makes later changes safer. Fixing state-code normalisation or a postal pattern in the shared matcher improves both stages rather than leaving one surface behind.
Make overlap visible instead of silently choosing a winner
Real supplier territories overlap.
One warehouse may serve all of Texas while a local store serves Houston with a different delivery promise. Two postal ranges can intersect. A city sits inside a state zone. Overlap can be intentional, but accidental overlap can also expose duplicate or conflicting shipping methods.
When a seller creates or updates a service zone, the platform compares the proposed geography with that seller's existing shipping zones. It recognises country, state, city and supported postal-pattern intersections and reports the conflicting zone and location.
By default, an unacknowledged overlap is rejected. The seller can explicitly confirm that the overlap is intended.
This is preferable to a hidden precedence rule. The system does not guess that the newest zone wins or that the smaller zone is always better. It asks the operator to own the commercial decision.
The current zone is excluded when it is being edited, so a saved zone does not conflict with itself. Tests cover state/city overlap, postal range/prefix overlap, explicit permission and edit behaviour.
Protect seller ownership when zones change
A service-zone identifier is not sufficient authority to update it.
Vendor-initiated changes first verify that the authenticated seller owns the zone through the marketplace's seller-to-service-zone relationship. The ownership check happens before mutation.
The vendor workflow then updates the service-zone data and, where the location has pickup enabled, synchronises the corresponding pickup geography. This prevents delivery and pickup territories for the same site from drifting merely because one configuration changed.
The seller boundary is essential in a marketplace. A valid service-zone ID belonging to supplier B must not become editable by supplier A.
This follows the same design used elsewhere in the platform: browser identifiers express the resource a user wants to change; server-side relationships decide whether that user owns the right to change it.
For the operator, the outcome is simpler configuration without sacrificing tenant isolation.
Turn a radius into maintainable geography
Some suppliers genuinely operate “within fifty miles of this location”.
The vendor tool can start from a postal code or coordinates, resolve a centre postal code and find nearby postal codes within a radius. It returns the corresponding cities grouped with canonical state codes, plus summary counts.
This helps the seller create a territory from an operational rule they already understand. They do not have to research every city surrounding a warehouse manually.
The radius computation is a configuration aid. It derives postal and city coverage from the configured centre and radius, while precise property-to-location routing belongs to the adjacent distance capability.
Keeping those concepts separate avoids false precision. A service zone answers whether the seller intends to serve an area. A route-distance record can later help rank eligible locations. One should not silently replace the other.
Connect territory changes to catalogue availability
A service zone affects more than the shipping page.
When a seller changes delivery topology, products connected to that seller or location may become deliverable or non-deliverable for different properties. The platform's shipping-topology layer can identify affected sellers and rebuild the relevant catalogue projection.
That matters because the marketplace uses Elasticsearch for product discovery. Geographic eligibility cannot live only in a relational shipping table if search continues presenting stale availability.
The canonical projection connects product, seller, fulfilment profile, shipping option, service zone and location. A topology change can therefore feed the same read model used by the storefront.
The supported business promise is precise: territory is treated as catalogue data as well as checkout data, with one explicit path for rebuilding the affected projection.
The buyer is less likely to discover the supplier's real boundary only after investing time in the cart.
Why Medusa was the right foundation
The client needed supplier-specific geography inside a shared marketplace.
Medusa already provided stock locations, fulfilment sets, service zones, shipping options and profiles. We could extend those primitives with seller ownership, structured matching, overlap governance, radius tooling, pickup synchronisation and catalogue projection.
On a rigid platform, marketplace operators often flatten this into one store-wide shipping table or maintain a separate eligibility service that has to be reconciled with checkout.
Medusa allowed geography to remain connected to the fulfilment capability it governs.
That is why the technology choice was architectural rather than fashionable. The base engine handled commerce mechanics; we added the exact supplier-territory model required by the client's operating reality.
A practical supplier-territory checklist
Before exposing delivery zones in a multi-vendor platform, define:
- Does the zone belong to a seller and a fulfilment location?
- Can suppliers choose country, state, city and postal granularity?
- Are state codes normalised across configuration and checkout?
- Is a city always matched with its state and country?
- Which postal expressions are supported: exact, numeric range and prefix?
- Are malformed or excessively broad patterns rejected safely?
- Do catalogue discovery and checkout share the same matcher?
- Are overlapping zones detected before save?
- Can a seller explicitly confirm an intentional overlap?
- Is seller ownership verified before every mutation?
- Does pickup geography follow the site's delivery geography where intended?
- Does a topology change update the affected catalogue projection?
- Is radius-based configuration distinguished from route distance?
These questions turn shipping zones into an operable supplier capability rather than a list of addresses.
The broader lesson
The client did not need a postcode field.
They needed every supplier to express where it could serve a property, using the geographic language its operation already understood. The marketplace then needed to apply that answer consistently when showing products and offering delivery.
We combined structured country, state, city and postal zones with normalisation, overlap controls, seller ownership and shared discovery/checkout matching. Radius tooling made local territories easier to configure without pretending that every business boundary is a circle.
For the buyer, availability became more credible. For the supplier, geography became a manageable commercial rule. For the marketplace, the catalogue and checkout stopped disagreeing about where an order could go.