Medusa Extend · AI
Creating a draft order by voice in Medusa
A sales rep dictates an order on their phone. The assistant finds the company and the product variants, checks the quantities and the stock, then asks for confirmation before creating a draft order in Medusa.
Take Linwood Clothing, a wholesaler that sells shirts and jackets to independent shops. Its Medusa application already holds its business customers, each with a buyer contact and addresses, and records which sales rep looks after each company. We are designing an ordering assistant for Linwood's sales reps.
Between two visits, Alex, one of the sales reps, sends a voice message to the assistant. Suppose the transcription service renders it as follows:
“Right, for So and So in Bristol, six navy blue Harbor Shirts in M and three in L.”
The transcript gets two names wrong. Alex was talking about Sew & Sew, a shop: in English, “sew” and “so” are pronounced the same way, and the service wrote the common expression “so and so”, a stand-in for someone left unnamed. Alex was also talking about the Harbour Shirt, a catalogue product: “Harbor” and “Harbour” are two spellings of the same word, American and British, and the service chose the first. Even with the right names, the sentence refers to things the way people do when speaking, whereas Medusa expects records: the identifier of a company and those of the two shirt variants Alex wants.
The goal is to create a draft order, an order in draft form in Medusa.
The transcription service turns the audio into text and knows neither Linwood's customers nor its catalogue. A language model reads that text, calls tools on the server to look up and check Linwood's data, and writes the questions Alex reads; together, the model and these tools form the assistant. A Medusa workflow creates the draft order only after Alex has confirmed a summary.
What the model draws from the transcript
Once the transcript arrives, the language model reads it. It has not yet called any search tool. It sorts the request into a fixed structure: which company, which lines, and for each line the product, the options and the quantity. For Alex's sentence, it produces:
- company: “So and So”, location “Bristol”;
- line 1: product “Harbor Shirt”, colour “navy blue”, size “M”, quantity 6 shirts;
- line 2: product “Harbor Shirt”, colour “navy blue”, size “L”, quantity 3 shirts. Alex only said “three in L”: the product and the colour are marked as carried over from line 1.
The server stores this result as the preparation record of Alex's message: a record belonging to the extension, separate from the Medusa draft order. Each value keeps the words it came from and carries a mark: said in the transcript, or carried over from another line. The identifier fields are empty. “So and So” is text, not a company record. “M” is a letter from the transcript, not yet a size the Harbour Shirt is known to come in.
Each quantity keeps its unit. “Six shirts” is stored as six shirts; “two packs” would be stored as two packs, without conversion.
The model is instructed not to fill gaps. If Alex had said “a few navy blue shirts in M”, the quantity would be marked as missing, not set to one. If the transcript gave two quantities for the same line without saying which one replaces the other, the model would ask Alex to repeat that part. The identifier fields stay empty during this extraction. Later, the model can only take an identifier from a tool result, and the server enforces this: it rejects any identifier that its own tools have not returned in this conversation.
Some transcription errors leave no trace. If Alex says “five” and the transcript writes “a hundred”, the sentence still reads normally, and nothing signals the error to the model. This is one of the reasons why Alex reviews a summary before anything is created.
The preparation record now holds a company name and two product lines, still in Alex's words. The assistant has to find the matching company and catalogue references, starting with the company.
Finding the company behind “So and So”
The model never receives Linwood's full list of companies. It may run to thousands of names, most of them not handled by Alex, and a copy placed in a prompt can become wrong as soon as a shop closes its account. Instead, the server gives the model a search tool: the model calls it with a few words, and the tool returns a handful of companies that Alex is allowed to order for.
The tool relies on Medusa's Search Module . The extension declares a company index : the name and the city are used for search, the status and the assigned sales rep serve as filters. The same definition lists the events that update the index when a company changes, and the extension's code must emit those events. The tool queries the index with query.search, which takes free text, filters and a maximum number of results. The server adds two filters to every call, active companies only and companies handled by Alex only, and the model cannot change them. Because an index can lag behind the data, the tool also re-reads each company it finds in the application's data before returning it.
Two kinds of gap can separate the transcript from a name stored at Linwood. The first is spelling: a missing accent, a swapped letter, “Harbor” for “Harbour”. The tool enables typo tolerance for these cases. With the PostgreSQL provider, the search compares words by three-letter sequences and ignores accents, so a name written slightly differently can still match. The second is a different word that sounds the same: in writing, “so” and “sew” share only their first letter. Typo tolerance compares letters, not sounds; nothing therefore guarantees that a search for “so and so” finds Sew & Sew.
Raising the number of results does not make a missing match appear. The limit cuts a list that is already filtered and ranked; if Sew & Sew is not in it, a longer list will not contain it either. It is the query itself that has to change.
So the model runs several short searches, each based on a different hypothesis:
- the words as transcribed, “so and so”;
- one or two spellings that the model judges compatible with the same sound, such as “Sew and Sew”;
- the location alone: the companies Alex handles in Bristol. There is then no text to rank, so the tool reads them directly from the application's data, filtered by city.
The city is not added as a filter to the first two searches. It is a clue, and a clue can be misheard too: if the transcript had got the city wrong, that filter would have excluded the right shop.
The server caps the effort: a few searches per mention, a few results per search. It merges the lists, removes duplicates and keeps at most ten candidates, a limit chosen for this example, each labelled with the search that found it. Here, the first search returns nothing. The second returns two companies: Sew & Sew in Bristol, and Sew & Sew in Cardiff, another shop with the same name. The third returns Sew & Sew in Bristol again, plus two other Bristol shops, Kite & Kin and Marlow Menswear. The server passes these four distinct companies to the model; Alex will only see those that need confirmation.
The model then compares each candidate with the transcript. Both Sew & Sew shops match the name requested by the second search, and a search score only ranks how close the text is: it does not tell the model which shop Alex meant. The city settles it: the transcript says Bristol, only one of the two is in Bristol, and that is also why the third search returned it. Kite & Kin and Marlow Menswear have only the city in common with the transcript. Sew & Sew in Bristol is the best-supported candidate, but its link to “so and so” rests on a sound-alike that the model assumed. So the model does not choose the company on its own. It will ask Alex to confirm Sew & Sew in Bristol, mentioning the Cardiff shop as another possibility.
If the transcript had given no city and no search had returned a convincing candidate, the model would not take the closest one. It would ask Alex for the city, the street or the spelling of the name, then run a new bounded search with the answer.
The company is not confirmed yet, but the model does not stop there. It moves on to the two lines, so that all its questions reach Alex in a single message.
From product name to available stock
Products go through the same kind of search tool, backed by a second index that the server restricts to products published in the sales channel of Linwood's B2B application. “Harbor Shirt” differs from “Harbour Shirt” only in spelling, and in this example the search returns three products: the Harbour Shirt, the Harbour Jacket and the Oxford Shirt. The model keeps the Harbour Shirt, the only one that matches both words of the transcript. If two products had matched equally well, it would have asked Alex.
Knowing the product does not yet give a line that Medusa can accept. The server runs three checks on each line.
The first concerns the variant : the combination of options that will actually be ordered. In Medusa, a product is sold through its variants. The Harbour Shirt comes in three colours, Navy, White and Olive, and in four sizes, Small, Medium, Large and X-Large (S, M, L and XL); each colour-size pair is a distinct variant, with its own identifier. The catalogue keeps these English labels. The server reads these options from the catalogue, not from the search index, and maps the words of the preparation record onto them: “navy blue” and “M” give the Navy / Medium variant, “navy blue” and “L” the Navy / Large variant. If Alex had said “XXL”, a size that does not exist for this shirt, the assistant would not replace it with X-Large: it would ask Alex, listing the sizes on offer. A line without a colour would also lead to a question.
The second concerns the quantity : a positive whole number, in the unit the catalogue sells. Linwood sells this shirt individually; if Alex dictates packs or cartons, the assistant asks how many shirts that represents. A missing or contradictory quantity is never filled in: the model asks the question. If Alex dictates “six in M” and then “two more in M”, the server checks both lines together, because it is their total that the stock must cover. If a second mention could be a correction rather than an addition, the model asks which it is before adding anything up.
The third concerns the available stock : how many units of this variant Linwood can sell in this sales channel. Medusa does not keep this number in a single field. A variant's stock is spread across stock locations, such as warehouses, and a sales channel is served by only some of them. At each location, the available quantity is the stock on hand minus what is already reserved. The availability of a variant in a channel adds up these quantities across the locations linked to that channel. Stock in a warehouse that does not serve the B2B channel does not count, and an announced delivery is only available once it arrives. The server's availability tool relies on Medusa's utility for this calculation. That utility also handles variants made up of inventory items: a pack of three can be configured to consume three units of the same inventory item as the single-unit variant, and the utility then counts how many packs that stock can supply. The tool also flags variants whose stock is not tracked: Medusa treats them as always orderable, and the calculation may return zero for them without their being out of stock.
More than three Navy / Large are available in the B2B channel. For Navy / Medium, the tool returns four, and Alex asked for six.
In this example, Linwood does not allow selling beyond stock (backorders): the assistant therefore cannot accept six shirts when four are available. It does not reduce the quantity to four on its own, does not switch the line to white shirts and does not promise a restock date it does not know. It flags the shortfall to Alex and asks whether to change the quantity to four or remove the line. It can also suggest the same shirt in White / Medium if the availability tool shows enough of it, but only as a suggestion that Alex has to accept. Medusa lets youallow backorders variant by variant; a wholesaler who wanted this would configure the rule on the server, and the model still could not enable it on a variant or a line.
Checking stock does not reserve it. Four shirts available now may be down to two an hour later; the server therefore re-reads availability just before creating the draft order.
Choosing the next step: search again, ask or propose
After these checks, line 2, three Harbour Shirt Navy / Large, has a variant identifier and an up-to-date stock check. Two points remain open: the company and the Navy / Medium quantity. The model now chooses between running another search, asking Alex a question and showing a summary to confirm, within the limits set by the server.
Before Alex confirms a summary, the model can call the search and read tools, and ask the server to update the preparation record. It has no tool that creates a draft order. The server checks each proposed update before saving it: an identifier is only accepted if one of its tools returned it, the number of searches per mention is capped, Alex must be allowed to order for the company, the variant must exist, the quantity must be a positive whole number of shirts, and the no-backorder rule applies. Only a confirmed summary opens the server's path to creating the draft order, as the last section describes.
The model starts from what the preparation record shows:
| Situation | What the assistant does next |
|---|---|
| A search returned a single candidate supported by the clues, without relying on an assumed spelling | It records this candidate and carries on checking the order without asking Alex. |
| No convincing candidate yet, and more searches are allowed | It runs another search on a different hypothesis, such as another spelling or the city alone. |
| No candidate after the allowed searches | It asks Alex for the city, the street or the spelling of the name, or for a product reference or description, then searches again with the answer. |
| Several plausible candidates, or a single one found through an assumed spelling | It asks Alex to confirm the candidate found through an assumed spelling, or shows two or three plausible candidates and asks which one is right. |
| An option or a quantity is missing | It asks a question about that field only. |
| A value does not exist in the catalogue, or two values contradict each other | It lists the values that exist, or asks Alex to repeat that part, without choosing itself. |
| Stock is insufficient | It states the shortfall and asks Alex to reduce the quantity, remove the line or accept another option whose stock has been checked. |
| All fields are settled | It shows a summary that Alex must confirm. |
Alex's order falls under two of these rows: a company to confirm and insufficient stock. The assistant keeps the fields already settled and groups the open points into a single message. As long as an answer is missing, no draft order exists. Alex reads:
“I couldn't find any shop called ‘So and So’ among your customers. Did you mean Sew & Sew in Bristol, or Sew & Sew in Cardiff? Also, only four Harbour Shirt Navy / Medium are available, and you asked for six. Shall I change the quantity to four, or remove this line?”
Applying Alex's answer without starting over
Alex replies after the next visit: “Sew & Sew, Bristol. Four is fine.”
The model ties each part of the answer to the field it concerns, “Sew & Sew, Bristol” to the company and “four” to the Navy / Medium quantity, and asks the server for these two updates. The server checks them and changes only those two fields. The company field now holds the identifier of Sew & Sew in Bristol, which the search tool had returned. The quantity of line 1 goes from six to four, with Alex's answer recorded as the source. Line 2 is not searched again.
Starting again from the transcript would invite new errors: the model might read “so and so” differently this time, or undo a variant the server had already checked. Treating all previous checks as still valid would be the opposite mistake: the stock check for line 1 compared four available shirts with six requested, and that comparison no longer describes the line. The server therefore records which fields each check depends on; when a field changes, it reruns the checks that depend on it, and only those. Here, the quantity of line 1 has changed, so the server reruns its stock check: four requested, four available.
Other answers would trigger other checks. If Alex had replied “six in white”, the server would have switched line 1 to White / Medium, kept six and checked that variant's stock. If Alex had chosen the Cardiff shop, the server would have checked that Alex can order for that company and re-read its buyer contact, its addresses and its pricing terms, along with any check that depends on them, because two companies in the same sales channel can have different prices. Both shops buy through this channel; the catalogue and stock checks would therefore remain valid.
Once all fields are settled, the server builds a summary of the preparation record and gives it a version number. Any later change produces a new version, and a confirmation is only valid for the version it answers. A “yes” to version 1 does not cover a version 2 in which a quantity has changed.
Alex reads version 1: Sew & Sew, Bristol; 4 × Harbour Shirt, Navy / Medium; 3 × Harbour Shirt, Navy / Large. Alex replies “yes”, and the server records that yes with the version number.
From “yes” to the draft order
The “yes” arrives on an API route of the extension, which checks that the message comes from Alex's account and hands the rest over to a workflow. The workflow begins with checks that involve no model and no search, only fresh re-reads of the data. Does the confirmation answer the latest version of the summary? Is Sew & Sew in Bristol still active, and still handled by Alex? Do both variants still exist, and are they still sold in the channel? Does the available stock still cover four and three shirts? If a check fails, for example because two Navy / Medium have been sold in the meantime, the workflow creates no draft order. The confirmation lapses, and Alex receives a new question on that point alone.
The draft order itself goes through Medusa's native path. The Admin route that creates draft orders calls createOrderWorkflow with the draft status, and the extension's workflow does the same. What Alex did not dictate comes from Sew & Sew's record in the application: its region, its sales channel, its buyer contact and its addresses. Prices never pass through the model: createOrderWorkflow calculates them from Medusa prices for this buyer and this region, and its hook setPricingContext lets the application add the company's pricing terms.
createOrderWorkflow also checks that variants whose stock is tracked have enough of it, and fails otherwise, unless backorders are allowed on the variant or on the line. This proposal allows neither: if stock drops between the last check and creation, the workflow stops and the assistant goes back to the stock question. The workflow does not reserve stock: the draft order does not set aside the four Navy / Medium.
One requirement remains to be implemented and tested in the extension: a “yes” must create only one draft order. The confirmation could arrive twice, or the server could stop just after creating the draft. The proposed mechanism gives each confirmation a creation key. Before creating the draft, the server claims this key in a way that can only succeed for a single process, then stores it with the draft order. If the same confirmation is processed again, the server returns that draft instead of creating another one. The link between the key and the draft must survive a crash and remain easy to find.
In this scenario, the workflow succeeds. Medusa holds one more draft order, for Sew & Sew in Bristol, with two lines and prices calculated by Medusa, and Alex receives a message saying so.