Post-Purchase Resolution
Shopping agents know how to buy. What happens when something goes wrong?
Post-Purchase Resolution is an agent-native post-purchase support experience built with WebMCP + Shopify.
Instead of forcing a customer to search for an order number, navigate support menus, or explain the same problem several times, the customer can simply describe what went wrong in natural language.
The agent can then discover the website's structured WebMCP capabilities, find the correct purchase, read authoritative Shopify state, and prepare the next step.
But there is one deliberate boundary:
The agent can help. It cannot silently become the customer or the merchant.
The customer keeps customer authority.
The merchant keeps merchant authority.
Shopify remains the external source of truth.
🎥 Demo
In the demo, a customer reports that a Portable 4K Action Camera — $149 arrived damaged and would not turn on.
The customer never provides an order number.
From that natural-language request, the agent discovers the site's WebMCP tools, finds the correct authenticated purchase, reads its return eligibility, and prepares a resolution.
Then:
Agent prepares → Customer commits → Merchant decides → Shopify records the truth.
💡 Inspiration
AI shopping experiences are becoming increasingly capable before checkout.
Agents can search.
They can compare.
They can recommend.
They can help people buy.
But commerce does not end at checkout.
Products arrive damaged.
The wrong variant is delivered.
Shipments arrive late.
Customers need exchanges, returns, replacements, or refunds.
And that part of the experience is still dominated by:
- order numbers
- support menus
- forms
- ticket queues
- policy pages
- repeated explanations
- disconnected customer and merchant workflows
That led us to a simple question:
If the web is becoming agentic, what should happen when the purchase itself goes wrong?
We did not want to build another chatbot floating on top of an ecommerce site.
We wanted the website itself to expose meaningful, structured capabilities that an agent could understand and use safely.
That is where WebMCP became the core of the product rather than an add-on.
✨ What it does
Post-Purchase Resolution lets a customer describe a purchase problem naturally.
For example:
“The action camera I bought recently arrived damaged and won't turn on. Can you find the purchase and tell me what I can do? Don't submit anything.”
The customer does not need to know the order number.
The agent discovers the site's available WebMCP tools and can use:
find_orderget_orderprepare_resolution
The experience then separates responsibility between three actors.
🤖 Agent
The agent can:
- understand the customer's intent
- locate the relevant purchase
- read authoritative order information
- inspect return eligibility
- prepare the appropriate resolution
The agent cannot commit the commerce action through WebMCP.
👤 Customer
The authenticated customer decides whether to actually request the return.
That action occurs under the customer's own Shopify Customer Account authority.
🏪 Merchant
The merchant receives the pending request in a separate decision desk.
Only the merchant can approve it.
🟢 Shopify
Shopify records the authoritative lifecycle of the return.
The website does not invent its own version of commerce state.
🔥 Why WebMCP matters
Without structured site capabilities, an agent often has to reason from presentation:
- inspect UI
- interpret text
- locate controls
- infer what a button means
- navigate DOM state
- hope the page still looks the same
Post-Purchase Resolution instead exposes explicit business capabilities.
Customer intent
↓
ChatGPT / Codex
↓
WebMCP Site Tools
↓
find_order
get_order
prepare_resolution
↓
Authoritative Shopify data
This means the agent does not need to guess that a certain button or piece of text represents an order lookup.
The site tells the agent exactly what capability exists.
And just as importantly, it tells the agent what capability does not exist.
🔐 The capability boundary
This became one of the most important design decisions in the project.
The WebMCP surface intentionally contains:
✓ find_order
✓ get_order
✓ prepare_resolution
It intentionally does not contain:
✕ request_return
✕ approve_return
✕ refund
That is not an unfinished feature.
It is the authority model.
The agent can find, read, and prepare.
The customer commits.
The merchant decides.
This allowed us to design the experience around collaboration instead of maximum agent autonomy.
More agent capability is not always better. The right capability at the right boundary is better.
🛍️ A real end-to-end scenario
One of our clean validation runs used a fresh Shopify purchase that was never hardcoded into the application.
The application discovered the purchase automatically.
The customer then followed the complete flow.
Fresh purchase
↓
Agent discovers purchase
↓
Agent prepares resolution
↓
Customer explicitly requests return
↓
Shopify Return = REQUESTED
↓
Merchant reviews request
↓
Merchant approves
↓
Same Shopify Return = OPEN
The critical part is that the same external Shopify Return object is preserved throughout the lifecycle.
The application is not maintaining a parallel pretend state.
Shopify is the system of record.
🧪 Real Shopify proof
We verified the architecture against a Shopify development store using test payments and real Shopify Order/Return objects.
A clean flow demonstrated:
| Step | Result |
|---|---|
| Fresh order discovered without hardcoding | ✅ |
| Customer-scoped purchase | ✅ |
| Agent mutation tool exposed | No |
| Customer requested return | ✅ |
| Shopify Return created | REQUESTED |
| Merchant reviewed same Return | ✅ |
| Merchant approved | ✅ |
| Same Shopify Return updated | OPEN |
| Duplicate Return created | No |
| Refund automatically performed | No |
This distinction matters.
The agent did not manufacture a UI result.
The state transition existed independently in Shopify.
🗣️ Natural-language WebMCP verification
We also tested the WebMCP experience through ChatGPT/Codex Site Tools.
The user described a damaged purchase without giving an order number.
The agent discovered and used:
find_order
get_order
prepare_resolution
It found the correct purchase and prepared the resolution.
Nothing was submitted.
An independent Shopify check confirmed:
Return created by agent: NO
Refund created by agent: NO
Approval event: NO
We then repeated the experience using a spoken request in a new chat with no previous order context.
The observed flow was:
Spoken request
↓
ChatGPT agent turn
↓
Website Site Tools enumerated
↓
find_order
↓
get_order
↓
Correct purchase found
The spoken request asked only to find the purchase and explain the available option.
The agent did exactly that.
It did not stage a resolution unnecessarily.
That gave us an interesting proof of intent-sensitive tool selection.
🏗️ How we built it
The product is built around four distinct layers.
┌─────────────────────────────┐
│ Customer / ChatGPT / Codex │
└──────────────┬──────────────┘
│
WebMCP
│
┌──────────────▼──────────────┐
│ Post-Purchase Resolution │
│ Vercel-hosted application │
└──────────────┬──────────────┘
│
┌────────┴────────┐
│ │
Customer Account Admin API
API │
│ │
▼ ▼
Customer action Merchant action
│ │
└────────┬─────────┘
▼
Shopify
External source of truth
WebMCP
The site registers structured tools through the browser's model context.
The final tool surface is deliberately small:
find_order
get_order
prepare_resolution
Shopify Customer Account API
The authenticated customer flow uses Shopify Customer Account authentication.
This keeps order discovery scoped to the currently authenticated customer's purchases.
The customer action uses customer authority.
Shopify Admin API
Merchant approval uses a separate server-side Admin authority.
The Admin credential is never exposed to the browser or agent.
Vercel
The public application and server-side API routes are deployed on Vercel.
Secrets remain on the server boundary.
🔑 Authentication and authority
Customer authentication uses OAuth/OIDC with PKCE.
The customer session is used to query purchases belonging to that authenticated customer.
The architecture does not permit arbitrary customer order enumeration from the customer flow.
The merchant side uses a separate operator access control in the current implementation.
That merchant access layer is intentionally distinct from customer authentication.
Current limitation:
The merchant decision desk uses an operator credential rather than full merchant OAuth/identity.
We document this explicitly rather than presenting it as something it is not.
🛡️ Security by capability design
Security was not treated as a final checklist item.
It influenced the WebMCP architecture itself.
Important boundaries include:
- customer-scoped order retrieval
- no arbitrary order lookup from authenticated customer flow
- Shopify Admin credentials remain server-side
- no commerce mutation exposed as a WebMCP tool
- POST-only mutation routes
- stale-state validation
- duplicate-return protection
- merchant approval access control
- expected invalid input handled without uncontrolled server errors
- public evidence sanitized for credentials and PII
Most importantly:
The safest mutation tool in this agent flow is the one we intentionally never registered.
📊 Evidence, not claims
We built the project around evidence that could be checked against explicit claims.
Final regression results:
| Suite | Result |
|---|---|
| Unit tests | 56 / 56 |
| Authentication security | 32 / 32 |
| Commerce security | 21 / 21 |
| Live UI | 12 / 12 |
| WebMCP capability boundary | 22 / 22 |
| Final customer → merchant flow | PASS |
| ChatGPT/Codex WebMCP verification | PASS |
We deliberately do not convert those results into a fake reliability percentage.
They prove the tested properties.
They do not prove universal reliability.
🧩 Challenges we faced
1. Finding the right role for the agent
The first instinct in an agentic product is often to expose more tools.
We learned that this was the wrong optimization.
The hardest design question became:
What should the agent intentionally NOT be allowed to do?
Removing the final mutation from the WebMCP surface made the product architecture stronger.
2. Separating customer and merchant authority
A return involves at least two different actors.
The customer may request.
The merchant may approve.
Those are not the same authority.
We designed independent customer and merchant paths instead of giving a single agent privileged access to both sides.
3. Making Shopify the source of truth
It would have been much easier to simulate the workflow locally.
We deliberately moved beyond fixture-only proof.
Returns were created and queried as actual Shopify Return objects inside a development store.
This exposed lifecycle details we would not have discovered in a mock-only implementation.
4. Customer-scoped purchase discovery
The product needed to find purchases naturally without turning order lookup into unrestricted order enumeration.
That required building the flow around authenticated customer data rather than arbitrary Admin-side search.
5. Lifecycle edge cases
Return state is not simply:
requested → approved
We encountered and handled states such as completed/closed returns and changed the UI to respect authoritative Shopify state instead of assuming a simpler lifecycle.
6. Evidence discipline
One of the biggest challenges was proving what the system actually did versus what we believed it did.
For example, an agent saying:
“Nothing was submitted”
is useful UX.
But Shopify showing no Return, no refund, and no application-attributed mutation event is much stronger evidence.
That distinction shaped how we validated the project.
📚 What we learned
WebMCP is most powerful when it expresses business meaning
The interesting part was not exposing a button to an agent.
It was exposing concepts such as:
find_order
get_order
prepare_resolution
Those are business capabilities rather than UI coordinates.
Intent-sensitive tools are better than giant tool surfaces
During one test, the user only asked the agent to find the purchase and explain the available option.
The agent used:
find_order
get_order
It did not call prepare_resolution.
When the user later asked for the next step to be prepared, the additional capability became relevant.
That is a better agent experience than exposing one giant “do everything” action.
Human authority can be part of the product, not friction
We initially thought about human approval as a safety step.
It became more than that.
It became the product's collaboration model:
Agent assists.
Customer commits.
Merchant decides.
External truth changes the quality of a demo
A UI saying REQUESTED is not enough.
Seeing the same Return in Shopify as REQUESTED, then the same object later becoming OPEN, made the architecture verifiable.
🌎 Potential impact
Post-purchase support is a large surface where consumers repeatedly provide information that already exists inside commerce systems.
An agent-native model could reduce that friction.
For customers
- describe the problem naturally
- no order-number hunting
- no support-menu maze
- maintain control over final actions
- see authoritative state
For merchants
- receive structured resolution requests
- preserve approval authority
- operate against existing commerce state
- avoid an AI system silently acting as the merchant
For agents
- structured capabilities
- authenticated business context
- less dependence on DOM guessing
- explicit authority boundaries
For the agentic web
Post-purchase resolution demonstrates that WebMCP can extend beyond information retrieval and pre-purchase shopping.
It can help websites expose structured workflows where humans and agents collaborate across meaningful business states.
🤝 Ecosystem
The project directly uses the following technologies.
OpenAI / ChatGPT / Codex
Used to verify natural-language discovery and execution of WebMCP Site Tools.
Shopify
Used for:
- authenticated customer purchases
- Customer Account API
- return eligibility
- return requests
- merchant approval
- real Order and Return objects
- external system of record
Vercel
Hosts the public application and server-side API routes.
Chrome / Chromium
Used during WebMCP runtime and compatibility testing.
We intentionally do not claim integrations with challenge supporters we did not actually use.
🚀 Try it
Live product
The public experience uses authenticated Shopify customer context.
Credentials are not published in the repository.
Source code
The repository includes:
- architecture
- WebMCP implementation
- security documentation
- evidence index
- Shopify setup guide
- ChatGPT Site Tools testing guide
- local installation instructions
- test suites
- sanitized evidence
Demo video
Watch the WebMCP Challenge demo
🧑💻 Run locally
The repository contains a complete setup guide for connecting your own Shopify development store.
At a high level:
git clone https://github.com/jpablortiz96/post-purchase-resolution.git
cd post-purchase-resolution
npm install
npm test
npm start
Shopify credentials and callback configuration are documented in the repository's setup guide.
No credentials are committed to source control.
🔭 What's next
The current version proves the post-purchase authority model.
Potential future extensions include:
- replacement workflows
- exchange workflows
- shipping-label generation
- carrier status
- richer merchant identity/OAuth
- merchant policy engines
- additional commerce platforms
- structured multi-item resolutions
- more post-purchase WebMCP capabilities
But we would keep one principle unchanged:
Expose the capability the agent needs — not every action the system can perform.
⚠️ Current limitations
This submission uses:
- a Shopify development store
- test payment transactions
- no real-money customer purchases
- operator-credential merchant access rather than merchant OAuth
- WebMCP verification from a specific ChatGPT/Codex client/version and test session
- existence proofs rather than reliability-rate claims
The spoken-request result demonstrates the observed flow:
spoken request
→ ChatGPT agent turn
→ Website Site Tools
→ WebMCP invocation
We do not claim that voice directly invokes WebMCP at the protocol transport layer.
🏁 Final thought
Shopping is becoming agentic.
Post-purchase support should not remain a maze of forms, order numbers, and disconnected systems.
But making support agentic does not require giving an AI unlimited authority.
It requires giving the agent the right structured capabilities, at the right moment, under the right authority boundary.
That is the idea behind Post-Purchase Resolution.
The agent helps.
The customer commits.
The merchant decides.
Shopify records the truth.
Post-Purchase Resolution — built for the WebMCP Challenge 2026.
Built With
- chatgpt
- chrome
- codex
- github
- graphql
- javascript
- node.js
- pkce
- shopify
- vercel
- webmcp
Log in or sign up for Devpost to join the conversation.