Accessible Action Mode — Returns & Exchanges

A shopper-controlled WebMCP workflow for conditional multi-item returns and exchanges.

Comment

Inspiration

What it does

How we built it

Challenges we ran into

Accomplishments that we're proud of

What we learned

What's next for Accessible Action Mode — Returns & Exchanges

Inspiration

People often describe a multi-item return as one outcome: “refund the jacket, exchange the shoes only if it is free, keep the coffee maker, and use a free drop-off.” Conventional returns interfaces split that intent across policy pages, item selectors, fee screens, and irreversible actions. An agent that merely clicks through those controls must guess what the merchant allows and when a real consequence will occur.

We wanted a safer, more accessible model: the agent prepares a precise plan from merchant-authoritative data, the page explains it in plain language, and the shopper keeps visible control over approval.

What it does

Accessible Action Mode — Returns & Exchanges lets a shopper state the desired outcome once. A compatible browser agent uses five explicit WebMCP tools to:

  1. Read the current order.
  2. Read authoritative return and exchange options.
  3. Stage one exact, reviewable resolution plan with no business side effect.
  4. Read the same plan displayed on the page.
  5. Apply it only after the shopper approves that exact plan using the ordinary page.

Approval, rejection, reset, and test-state controls deliberately remain page actions. There is no agent-facing approval or rejection tool.

Demonstrated workflow

The fictional test order AAM-2048 contains three items:

  • Midnight Field Jacket — $74.00 refund.
  • Stone Running Shoes — exchange from size 8.5 to size 9 at $0.00.
  • Matte Countertop Coffee Maker — keep.
  • Free QR drop-off.
  • Total refund — $74.00.
  • Additional cost — $0.00.

Before approval, the page clearly says NOT SUBMITTED. Applying early returns APPROVAL_REQUIRED. After page approval, the plan applies exactly once in the local simulation; a repeat attempt returns DUPLICATE_EXECUTION without a second effect.

Why WebMCP is essential

Without WebMCP, an agent has to infer intent and policy from page-specific widgets, labels, disabled controls, and prose. WebMCP lets the page expose merchant-intended action contracts, constrained inputs, authoritative state, and side-effect boundaries directly.

The five registered tools are:

  • get_order
  • get_return_exchange_options
  • stage_resolution_plan
  • get_resolution_plan
  • apply_approved_resolution

The agent and shopper share one server-backed plan, so they do not drift into separate interpretations of the return.

How we built it

The application uses TypeScript, React/Vinext, Cloudflare D1, Drizzle, deterministic policy functions, and document.modelContext.registerTool(...). Each authenticated principal receives an isolated workspace. Plans capture order, item, policy, and plan versions; expire automatically; record approval attribution; enforce idempotency; and emit ordered audit events.

The ordinary page remains fully usable when WebMCP is unavailable. It supports keyboard navigation, visible focus, labeled controls, live-region errors, responsive reflow, reduced-motion preferences, and the same review and page-approval journey.

ChatGPT served as the browser-agent client. Codex supported the specification, implementation, testing, accessibility work, deployment preparation, and evidence review. Human review set the safety boundaries and retained control over credentials, publication, and approval.

Challenges

The hardest part was preserving a clear authority boundary while keeping the experience useful. We had to make staging helpful but consequence-free, bind approval to the exact plan and versions the shopper reviewed, reject stale or expired state atomically, and guarantee that retries cannot create duplicate effects.

We also separated the Shopify proof from the execution claim. The authorized development-store path demonstrates read-only order, returnability, and calculation evidence. Staging and apply remain an isolated local D1 simulation. The project performs no real return, refund, payment, fulfillment, inventory, label, carrier, or merchant mutation.

Accomplishments

  • Exactly five focused WebMCP tools and no approval tool.
  • A coherent shopper-and-agent workflow rather than a technical-only demo.
  • 109 passing unit/integration tests and two Playwright journeys.
  • Verified authentication, tenant isolation, stale-state, expiry, rejection, atomicity, and duplicate-execution guards.
  • Keyboard and responsive accessibility coverage with zero reported axe violations in the verified browser run.
  • Public live site, Apache-2.0 source repository, and a public 2:48 narrated demo.

What we learned

WebMCP is strongest when it exposes a domain workflow instead of wrapping arbitrary UI automation. Structured tools make the agent more accurate, but they do not replace ordinary accessibility or human authority. For consequential commerce actions, the most useful collaboration is: agent reads and prepares, page enforces policy, human approves, and the server revalidates everything.

What's next

A production Shopify product would add shop-scoped installation and OAuth, encrypted per-shop credentials, customer authentication, compliance webhooks, generalized policy mapping, reconciliation, monitoring, support, and a reviewed distribution path. This challenge build intentionally stops at a safe synthetic and read-only provider boundary; it does not claim App Store readiness or live Shopify return processing.

Built With

Share this project:

Updates

Submission history