Returns and refunds
It is the question that costs a store the most to answer badly, because every wrong sentence is a promise someone has to take back later. Refik does four things with it and stops: it reads your return policy out of your store rather than from memory, it works out whose order this is, it checks four conditions, and then it opens a return request — which a person approves in Shopify admin. The assistant is told, in the tool’s own reply, not to say the return is approved. This page is that whole walk, read out of the code that ships.
The policy
A return answer starts with one lookup. The tool that serves it takes a single argument with two allowed values — shipping or returns — and the assistant is instructed never to answer a question about a return window from memory. What comes back is your own policy, plus the address of your own policy page, so the shopper can read it where you wrote it.
One wording choice is worth naming, because it was made deliberately and it is the kind of thing an assistant gets wrong on its own. The policy text handed to the model describes the forbidden phrasings instead of quoting them. A tool reply is a surface the model genuinely accepts; a banned phrase appearing there — even in order to ban it — reads to the model as an available phrase. The ban itself lives in the system prompt, with its wording, where the model is not reading it as an example.
Whose order
Order numbers in a Shopify store run in sequence, which is the whole problem: a number alone is a guess anyone can make, and guessing them in order is a strategy. So there are exactly two ways into an order, and a signed-in shopper is the easy one.
Four gates
Each gate returns its own sentence when it closes, and each of those sentences tells the assistant what to do next instead of leaving it to improvise. None of them is a general refusal: every one of them ends in either a question for the shopper or a hand-off to your team.
Gate one
The confirmation is a required field on the call, and it has to be true. The assistant cannot satisfy it by claiming to have asked — the confirmation lives in the call itself, which is a gate that does not take the model’s word for anything.
Without it the reply asks the assistant to go and ask, and on a store with the hygiene exemption it says why: opened items cannot be returned.
Gate two
Either the shopper is signed in, or the order was found earlier with the number and the e-mail together. Nothing else counts, and an order number on its own never counts.
When it fails, the reply spells out the recovery in order: ask for the number and the e-mail, look the order up, then call again.
Gate three
The order’s returnable lines are fetched before anything is written. An order with none — already returned, or not yet delivered — stops here.
The reply names both possibilities without picking one, and offers the hand-off, because which of the two it is depends on a record the assistant cannot read.
Gate four
The days are counted from the delivery date against your store’s own window. Past it, the request does not open; the reply carries the number of days that have passed and asks the assistant to explain it kindly and offer the team, who can still look.
And where the delivery date is unknown, the window is not enforced — a guessed date would reject a real return. Human approval is already in the path, so the honest move is to let a person see it.
The reason the shopper gives is carried as one of four codes, and damage is missing from that list on purpose. A damaged or defective item is not a form to fill in — the tool description tells the assistant to hand those to a person instead, and the hand-off tool names damaged goods and return disputes among the things it exists for. There is a second detour before any of this: a shopper who is simply unhappy with how a product performed is sent to the troubleshooting tool first, because most of the time that is a usage problem and it can be fixed.
Your throttle
The research finding behind this was not that merchants want a better assistant. It was that they want a dial. So permission is held per tool rather than per assistant, and the tool that opens a return is one of three that do not start in the open position.
acik — works normallyonayli — does nothing without the shopper’s explicit confirmation, and for this tool that confirmation is the unopened field itselfdevret — the tool exists, but calling it sends the work to a person; the assistant does not do it itselfkapali — the tool is never offered to the model, so it does not know the capability exists and cannot say it doesThat last distinction matters more than it looks. A tool handed off is one the shopper can still ask for; a tool switched off is one the assistant will not mention.
Two shapes exist in this category and both were designed for e-mail queues: staged rollout, and a percentage of incoming tickets. Neither transfers to live chat, where a draft mode means holding the shopper while a person reads — and that is a live hand-off, not a mode. A dial per capability is what that constraint leaves, and the return tool is the clearest case for it: the gates above are the product’s own caution, and this setting is yours.
Honesty
A return is the moment an assistant is most tempted to say something comforting, and the comforting sentence is usually the one the store has to walk back. Four places where this one stops short, in the same voice as the rest.
The reply that comes back after a request opens carries the instruction in capitals: tell the shopper it has been submitted, and do not say it is approved. Approval happens in Shopify admin, by a person, and it is the one step this never takes.
Where a store sends a return label, the assistant is told the order of the sentence — acceptance first, label second — because any wording that skips the acceptance step overstates the policy. Where a store has not confirmed it sends one, the assistant is told to say nothing about a label at all, and to let the team explain the next step.
Damaged and defective items are missing from the reason codes by design, and the instruction is explicit: do not open a request, hand it over. A photograph may be part of your process, and whether one can be asked for is a flag your store sets rather than something the assistant decides.
Which gates exist, what each one returns and which word is forbidden are all on this page and all read out of the code. The figure that belongs beside them is not: how many return conversations end in an opened request, and how many of those a store approves.
Questions
No. The only write it performs on an order is opening a return request, and that request sits unapproved until a person in Shopify admin accepts it. There is no refund call anywhere in the path, and the reply the assistant reads after a request opens tells it not to describe the return as approved. What the app can and cannot write is listed under access scopes.
Not for a guest. The guest lookup requires the number and the e-mail together, both of them, and the assistant is told never to call it with one. The alternative it offers is signing in, which is the stronger check anyway. The reason for the rule is arithmetic: order numbers run in sequence, so a number on its own is a guess, and an assistant that accepted guesses would read out somebody else’s order.
Two things. Attempts are counted per conversation against a cap of five, and over the cap the reply tells the assistant to stop rather than to try again. And the failure message is the same whichever half was wrong: no order matches that number and e-mail, with an explicit instruction not to guess which one. A reply that distinguished the two would be feedback, and feedback is what makes scanning work.
It says how long, and then it offers your team. The reply carries the number of days since delivery and your store’s own window, and it asks the assistant to explain that kindly and hand the conversation over to people who can still look at it. The one case where the window is not applied is an order with no known delivery date — rejecting a real return on a guessed date would be worse than letting a person see it.
Not on the first turn. The return tool’s own description sends that case to the troubleshooting tool first, on the grounds that most of the time it is a usage problem and can be fixed — and a fixed product is better for both sides than a returned one. If it genuinely is a return after that, the four gates are still the four gates. If it is damage or a dispute, it goes to a person instead.
Yes, and there are two different ways to do it. Hand it off and the shopper can still ask for a return; the work lands with your team instead. Switch it off and the tool is never offered to the model at all, so the assistant does not mention returns as something it can do. Both are per-tool, so nothing else changes. The one tool you cannot switch off is the hand-off itself.
Everything on this page was read out of the code that ships: the two allowed topics of the policy lookup, the two routes into an order, the attempt cap, the four gates and the sentence each one returns, the four reason codes, the four permission settings and the three tools that start at confirm-first. Where this page and your own store disagree, the bug is on this page and we would like to hear about it. The surface a return conversation actually happens on is the chat bubble, and what the assistant reads before it answers anything is under what it reads.