returns

name

returns

description

Process returns for any retailer end-to-end. Starts by searching email for the order confirmation, extracts order details, navigates to the retailer's return portal, completes the return flow, captures QR codes or return labels, and updates a persistent markdown tracker with PDF export. Use this skill whenever the user mentions returning an item, starting a return, 'I need to return', 'send back', 'refund', managing pending returns, or checking return status. Also trigger when the user asks about their returns tracker, outstanding returns, or 'what do I need to drop off'. Works with Amazon, Vuori, L.L. Bean, Quince, and any other retailer.

Returns Skill

You are helping the user process a return from start to finish. This works for any retailer -- Amazon, Vuori, L.L. Bean, Quince, etc. When the environment supports it, the workflow can also produce a well-organized tracking file (markdown + PDF) the user (or their assistant) can reference when physically making the return.

Best Results

This skill works best when the agent has both:

• Email access to find order confirmations, return confirmations, and label or QR-code links
• Browser access to navigate retailer order pages and complete the return flow

It can still work with partial access, but the workflow is fastest and most reliable when both are available.

Fallback Modes

Choose the strongest mode the current environment supports:

• Email + browser access: full workflow. Find the order, complete the return online, capture the QR code or label details, and optionally update the tracker.
• Email access only: extract order and return details from email, identify likely return links or instructions, and optionally update the tracker with manual next steps for the user.
• Browser access only: complete the return through the retailer portal if the user can supply order details manually, then summarize what they need for drop-off or shipping.
• Neither email nor browser access: collect the required details from the user and provide a manual checklist of what they need to do next.

The tracker and PDF are helpful add-ons, not the core goal. The primary success condition is getting the return completed or giving the user the shortest path to complete it.

File Locations

All return-related files go in a returns/ subfolder inside a workspace root chosen for this task.

By default, use the current project or working directory unless the user has a dedicated workspace they want to use. If they specify another location, use that as the workspace root consistently for all files created by this skill.

• Tracker: returns/returns-tracker.md
• Return cards / QR codes: returns/return-card-[item-slug]-[YYYY-MM-DD].jpeg (or .png)
• PDF: returns/returns-tracker.pdf

Create the returns/ directory if it doesn't exist.

Dependencies

• An email source is strongly preferred for finding order confirmations and return emails. Use any available email connector or mail client access. If Gmail is available, use it. Otherwise use the best available mailbox access or ask the user for the relevant order email.
• A browser automation tool is required for most retailer portals. Use the best available browser tool in the current environment.
• PDF generation is optional. Prefer pandoc when available, but do not block the workflow if only the markdown tracker can be produced.

Before You Begin

Gather return details from the user. Before searching email or touching the browser, you need:

1. Which item -- product name, retailer, description, or enough to find it in email / order history
2. Reason for return -- why they're returning it (defective, wrong item, didn't like style, etc.)
3. Condition details (only if ambiguous) -- You can infer most condition answers from context. Only ask the user if something is genuinely unclear:
   • If the reason is "no longer needed" / "changed mind" / "didn't like style," assume: packaging opened, item in good condition, all accessories included.
   • If the reason is "defective" or "damaged," ask: "Is there any visible damage I should note?"
   • Always ask if unsure: "Are all accessories and parts included with the return?"

If the user didn't provide a reason, ask -- most return portals require one.

Automation Philosophy

This skill runs fully automated when the environment supports it -- do not pause for confirmation between steps. The user expects you to drive the return flow from start to finish without asking "is this right?" at each stage. The only exceptions where you must stop and involve the user:

• Login/CAPTCHA: You cannot enter credentials or solve CAPTCHAs. Stop and ask the user to handle it, then resume.
• Ambiguous item match: If the search turns up multiple plausible items and you genuinely can't tell which one the user means, ask. But if there's a clear best match, just go with it.
• Payment required: If there's a payment step (e.g., shipping fee), stop and let the user complete payment. Do not enter payment information.
• No return methods available: If the retailer shows no eligible return methods or the return window is closed, stop and report.

Everything else -- selecting reasons, choosing the return method, clicking through confirmation screens -- just do it.

---

Optional Tracking Output

If the user wants ongoing return management, maintain a returns/returns-tracker.md file and optionally export returns/returns-tracker.pdf.

Use the tracker when the user wants any of the following:

• A persistent list of pending returns
• QR codes or label links saved in one place
• A summary of what still needs to be dropped off
• A PDF handoff for an assistant or family member

If the user only wants the return completed and does not ask for tracking, you can skip tracker creation entirely.

Checking Pending Returns

When the user asks about pending returns ("what do I need to drop off?", "what returns are outstanding?", "do I have anything due soon?"):

1. Read returns/returns-tracker.md and look at the Quick Reference and Detailed Return Records sections
2. Summarize by drop-off location so the user can batch trips (e.g., "You have 2 items for Whole Foods and 1 for USPS")
3. Flag approaching deadlines -- call out any returns due within the next 7 days, and mark any that are overdue
4. Give an actionable summary -- tell them what to bring, where to go, and what's most urgent

This is a read-only operation -- don't modify the tracker.

Adding an Existing Return to the Tracker

Sometimes the user has already initiated a return themselves and just wants it tracked. In this case:

1. Ask what they need: retailer, item, return method, deadline, QR code or label situation
2. If they have a confirmation email, search their email for it to fill in details
3. Add the entry to the tracker following the standard format
4. If they have a QR code image or return card, save it to the returns/ folder

---

Abridged Flow: Add a Return from a Confirmation Email

Sometimes the user has already completed the return themselves (on their phone, through the Amazon app, etc.) and just wants it tracked. They might say "I already started a return for X, add it to the tracker" or "check my email for that return confirmation and add it."

In this case, skip Phases 1-3 entirely:

1. Search the user's email for the return confirmation email (for example, from:[e-mail] or from:<retailer> return confirmed)
2. Read the email to extract: item name, return method, drop-off location, deadline, refund amount, order number
3. Jump straight to Phase 5 (update the tracker, if the user wants tracking) and Phase 6 (generate PDF, if useful)
4. If the user has a QR code screenshot or return card image, save it to the returns/ folder

This is also the right approach when browser automation hits a wall (login issues, CAPTCHAs, broken pages) and the user finishes the return manually — just pick up from the confirmation email.

---

Phase 1: Find the Order (Email-First)

Default: Search email first. This is faster and more reliable than navigating retailer websites.

1. Search the user's email for the order confirmation email. If Gmail-style search is available, use queries like:
   • from:<retailer> subject:order confirmed or from:<retailer> subject:order confirmation
   • from:<retailer> subject:"order #"
   • from:<retailer> with the product name as additional search terms
   • If the user gave an order number: subject:<order-number> or "<order-number>"
   • Fallback queries if the above return nothing: from:<retailer> subject:shipping, from:<retailer> subject:delivered, or just from:<retailer> sorted by date
2. Read the confirmation email to extract:
   • Order number
   • Item names, sizes, colors, quantities, prices
   • Order date
   • Payment method
   • Any return-related links (return portal URL, "start a return" button, order status page)
3. Identify the return portal. Look in the email for:
   • Direct "Start a return" or "Return this item" links
   • Links to the retailer's order status page (which usually has a return option)
   • The retailer's returns URL (often in the email footer, e.g., "Free Returns" link)
   • Common return portal patterns: returns.narvar.com/<retailer>/returns, <retailer>.com/returns, returnscenter.<retailer>.com

Fallback: Go to the retailer's website directly only if:

• Email search finds nothing (user may have used a different email, or it's an in-store purchase)
• The email doesn't contain enough info to identify the items or find the return portal
• The user explicitly asks you to go to the website

When using the website fallback:

• Navigate to the retailer's orders page or return portal
• For Amazon: https://www.amazon.com/your-orders
• For other retailers: check for an "Orders" or "Returns" link, or try common URLs like <retailer>.com/account/orders
• If not logged in, stop and tell the user to log in first

---

Phase 2: Initiate the Return via the Retailer's Portal

Navigate to the return portal (URL found in Phase 1) using the best available browser automation tool in the current environment.

If multiple browser tools are available, prefer the one with the strongest page-reading and form-interaction support. If Claude in Chrome is available, it is a good default. Otherwise use any equivalent browser automation tool that can navigate pages, inspect interactive elements, fill forms, run small JavaScript snippets, and capture screenshots.

General flow (works for most Narvar-powered and similar portals):

1. Open the return portal URL in the browser

2. Enter order details if prompted (order number, email address, zip code -- get these from the email)

3. Select the items to return. Click/check only the items the user wants to return, skip items they're keeping.

4. Select the return reason. Map the user's reason to the closest option:

   • "didn't like style" / "changed mind" --> "Just Don't Love It" / "Changed Mind" / "My needs changed" / "Style preference"
   • "defective" / "broken" --> "Defective" / "Product is defective"
   • "wrong item" --> "Ordering Issue" / "Wrong item received"
   • "doesn't fit" --> "Fits too small/large" / "Not Compatible"

5. Choose the return method based on this priority:

   Priority	Method	Why
   1st	Printerless / QR code drop-off	No printing needed, just show QR code
   2nd	Whole Foods drop-off (Amazon)	No packaging needed, no label needed
   3rd	USPS / UPS / FedEx drop-off	Widely available
   4th	Mail-back with printed label	Requires printing
   5th	Scheduled pickup	Convenient but may cost extra

   Prefer free options over paid. If the user has expressed a different preference, respect that.

6. Select refund method if prompted. Prefer refund to the original payment method over store credit.

7. Confirm and submit the return.

---

Phase 3: Capture the Return Code / Label

After the return is confirmed, you need to capture whatever the user needs to physically complete the return.

For QR code returns (printerless drop-off):

1. Look for the QR code on the confirmation page. Check for:
   • An image with alt text containing "QR", "code", "printerless", or "return"
   • A button like "GET MOBILE RETURN CODE" or "View Return Code" -- click it (it may open a new page/tab or use window.open)
   • If a button uses window.open and doesn't navigate, intercept the URL:

     const origOpen = window.open;
     window.__capturedUrl = null;
     window.open = function(url) { window.__capturedUrl = url; return origOpen.apply(this, arguments); };
     // click the button, then check window.__capturedUrl
     

2. Download the QR code image directly using Python if possible:

   import urllib.request
   req = urllib.request.Request(qr_url, headers={'User-Agent': 'Mozilla/5.0', 'Referer': '<return-page-url>'})
   data = urllib.request.urlopen(req).read()
   with open('returns/return-card-<slug>-<date>.png', 'wb') as f:
       f.write(data)
   

3. If direct download fails, fall back to screenshotting the QR code page.
4. Extract any reference IDs from the page (RMA ID, Label Broker ID, return confirmation number).

For QR codes on Amazon specifically:

Amazon's QR code images are hosted on S3 with CORS restrictions. Use a screenshot-based approach instead:

1. Wait for the confirmation page showing "Your return request is confirmed"
2. Click "Return code" to expand the QR code section
3. Use JavaScript to find the QR image bounding box, then screenshot and crop with Python/Pillow
4. Do NOT click the "Download" button -- it triggers a native Save dialog that can't be automated
5. Extract the RMA ID from the page text

For return labels (print-and-mail):

1. Don't try to download or screenshot the label itself. Instead, capture the link:
   • The return confirmation email (which the retailer sends after you submit the return) almost always contains a "Print return label" link
   • The return confirmation page may also have a "Print label" or "Download label" link
2. Save both links in the tracker:
   • Link to the confirmation email in the user's mail system, if a stable message URL is available
   • Direct link to the print-label page if available on the retailer's site
3. This lets the user (or their assistant) click through and print whenever they're ready.

For scheduled pickups:

1. Note the pickup date, time window, and any instructions
2. Note whether packaging/labeling is required before pickup

---

Phase 4: Check for Confirmation Email

After the return is submitted, the retailer usually sends a confirmation email with the QR code, return label, or tracking info.

1. Search the user's email for the confirmation email: from:<retailer> return OR "return code" OR "return label" after:<today's-date>
2. Read the email to extract any additional info (tracking links, QR code links, label links)
3. Save a message reference for the tracker:
   • A stable webmail URL if one exists
   • Otherwise the message ID, subject, sender, and date

---

Phase 5: Update the Returns Tracker (Optional)

Only do this phase when the user wants persistent tracking.

Read the existing tracker file. If it doesn't exist, create it from scratch.

Tracker location: returns/returns-tracker.md under the chosen workspace root.

Use this format for each return entry:

### [Item Name(s)]
- **Retailer:** [retailer name]
- **Order date:** YYYY-MM-DD
- **Return started:** YYYY-MM-DD
- **Status:** Ready to drop off | Ready to ship | Pickup scheduled | Completed
- **Return method:** [method + carrier, e.g., "USPS Printerless drop-off (FREE)"]
- **Location/Instructions:** [e.g., "Take to Elmwood USPS Post Office (2705 Webster St) -- show QR code, no printing needed"]
- **QR code / Return card:** [return-card-item-slug-YYYY-MM-DD.png](return-card-item-slug-YYYY-MM-DD.png)
- **Confirmation email:** [message link or reference]
- **Refund:** $XX.XX to [original payment method] -- pending
- **Deadline:** Return by YYYY-MM-DD
- **Order #:** XXXXXXXXX
- **Notes:** [reason, condition, anything else relevant]

Tracker file structure:

# Returns Tracker

Last updated: YYYY-MM-DD

## Quick Reference -- What Needs to Go Where

This section is the at-a-glance summary someone needs when heading out to make returns. Group pending returns by drop-off location so the person making the returns can batch trips.

### Whole Foods
- Item A -- no box needed, show QR code to store associate -- **drop off by April 16**
    - Return card: [return-card-item-a-2026-03-30.jpeg](return-card-item-a-2026-03-30.jpeg)

### USPS Post Office
- Item B -- box it up, show QR code to associate (no printing needed) -- **drop off by July 24**
    - QR code: [return-card-item-b-2026-04-04.png](return-card-item-b-2026-04-04.png)

### UPS Store
- Item C -- no box needed, show QR code -- **drop off by May 1**
    - Return card: [return-card-item-c-2026-03-30.jpeg](return-card-item-c-2026-03-30.jpeg)
- Item D -- print label, box it up
    - [Print return label (from confirmation email)](https://example.com/message-or-label-link)

### FedEx
- (none right now)

### UPS Pickup Scheduled
- Item E -- pickup on YYYY-MM-DD, leave sealed package by front door

---

## Detailed Return Records

[Full entries with all metadata for each item]

---

## Completed Returns

[entries moved here once the user confirms they dropped it off]

The "Quick Reference" section is the most important part -- it's what someone (the user or their assistant) will actually look at when heading out the door. Keep it scannable and grouped by location.

When adding a new entry:

1. Read the existing file first (if it exists)
2. Add the new return under "Detailed Return Records" with full metadata
3. Update the "Quick Reference" section to include the new item under the right location heading
4. Always include the deadline in the Quick Reference line (bold, e.g., "drop off by April 16"). Within each location group, list the most urgent deadlines first.
5. Keep completed returns in their section
6. Save any QR code / return card images to the same returns/ folder

---

Phase 6: Generate PDF (Optional)

After updating the markdown tracker, convert it to a PDF if the user wants a printable or shareable handoff:

cd /path/to/returns && pandoc returns-tracker.md -o returns-tracker.pdf --resource-path=.

If pandoc isn't available, try weasyprint or any other available converter. If PDF generation fails for any reason, don't let it block the return -- the markdown tracker is the source of truth. The PDF is a convenience.

---

Phase 7: Summary

After everything is done, give the user a one-line summary like: "Done -- [item] return started. Drop off at [location] with the QR code by [date]. Tracker and PDF updated." Don't rehash what's already in the tracker.

---

Amazon-Specific Reference

This section contains Amazon-specific details. Only use this section when processing an Amazon return.

Amazon return portal

Navigate to https://www.amazon.com/your-orders and find the item. Click "Return or replace items."

Amazon reason selection

Amazon uses a two-step reason selection: broad category first, then a specific reason.

Primary categories: Damaged, Changed Mind, Defective, Ordering Issue, Not Compatible, Delivery Issue, Not as Expected

Mapping user reasons to Amazon categories:

• "no longer needed" / "changed my mind" / "don't want it" --> Changed Mind --> My needs changed
• "bigger/smaller than expected" / "too large" / "too small for my space" --> Changed Mind --> My needs changed (do NOT use "Incorrect Size" — it triggers a troubleshooting detour for many product categories and is meant for wrong-size-shipped scenarios, not "I misjudged the dimensions")
• "defective" / "doesn't work" / "broken" --> Defective (or Damaged if physical damage)
• "wrong item" / "not what I ordered" --> Ordering Issue
• "arrived late" --> Delivery Issue
• "doesn't fit" / "not compatible" --> Not Compatible
• "found it cheaper" --> Changed Mind --> Found a better price

Amazon AI-powered reason flow (Rufus chat)

Amazon now uses an AI chatbot ("Powered by ai") for the return reason flow instead of simple dropdowns. This changes the interaction model significantly:

1. After selecting a primary reason category (e.g., "Incorrect Size", "Changed Mind"), Amazon presents a chat-style interface that asks follow-up questions.
2. To submit a response: Type in the textarea, then find and click the submit button. The submit button is a small (24x24px) button[type="submit"] with class rufus-web-submit-button positioned at the right edge of the textarea. Use JavaScript to locate it precisely:

   const btn = document.querySelector('.rufus-web-submit-button');
   const rect = btn.getBoundingClientRect();
   // Click at center of rect
   

   Alternatively, use form_input to set the textarea value, then click the submit button by coordinates.
3. Do NOT press Enter to submit — it may insert a newline or do nothing.
4. The sidebar "Continue" button only becomes active after the chat conversation completes (Amazon's AI says something like "Thanks, your feedback helps improve future shopping experiences"). Clicking Continue before the chat finishes will not advance the flow.
5. Multiple follow-up questions are common. The chat may ask 2-3 questions (e.g., "What was the sizing issue?", "Was there anything inaccurate about the product description?"). Answer each one concisely and submit.

Amazon item condition questions

After the reason, Amazon may ask about item condition with clickable buttons. Defaults for "no longer needed": packaging opened, item in original packaging, used, no signs of use, all accessories included.

Important: There may be duplicate buttons on the page for other items in the same order. Use read_page with filter: "interactive" or find to locate the correct element references.

Amazon troubleshooting / product support detour

Amazon may show a "Troubleshoot on your own" or "Get Product Support" page with categories like "First-time setup", "Unstable / Wobbles", etc. This happens in two cases:

• After selecting certain reason categories (notably "Incorrect Size", "Not Compatible", "Defective")
• As an intermediate "How can we make it right?" page

To get past it: Use find to locate the "Continue to return options" button — it exists in the DOM but may be off-screen below the troubleshooting categories. Use scroll_to with the element ref to bring it into view, then click it. Do NOT try to scroll by coordinates — Amazon's SPA rendering frequently produces blank viewports when scrolling by pixel offset. Always prefer scroll_to ref on Amazon pages.

Amazon refund method selection

Prefer refund to original payment method (Visa/card), not Amazon account balance. The card option is typically shown as a link below the balance option -- click it to expand.

Amazon return method priority

Priority	Method	Why
1st	Whole Foods drop-off	No packaging needed, no label needed
2nd	UPS drop-off	No packaging needed with QR code
3rd	FedEx drop-off	Similar to UPS but less preferred
4th	Schedule UPS pickup	Convenient but costs $6, wide time window

Amazon "Keep item" popup

After clicking "Confirm your return," Amazon may ask: "Would you like to keep the item and get a partial refund instead?" Always click "No, I want to return it."

Amazon QR code capture

Amazon QR codes are on S3 with CORS restrictions. Use screenshot + crop approach:

1. Click "Return code" to expand the QR section
2. Use JavaScript to find the QR image bounding box
3. Screenshot and crop with Python/Pillow
4. Do NOT click "Download" -- it triggers a native Save dialog

Fallback for UPS Store returns: The "Return code" button on the web confirmation page may not display a QR code inline — for UPS Store returns, the return code is often only accessible via the Amazon mobile app (Your Orders → Return details → Return code) or the confirmation email. If the QR code doesn't render on the web page after clicking "Return code", note in the tracker that the user should pull it up on their phone at the UPS Store. Don't waste cycles trying to capture what isn't there.

Amazon UPS pickup

• Amazon handles scheduling within its own interface
• Pickup window is typically 9-12 hours, cannot be narrowed
• No UPS account needed, no label printing needed
• Cost is typically $6 (sometimes waived for defective items)

---

Error Handling

• Order not found in email: Ask the user for more details (retailer name, approximate date, price). Try broader search terms. Fall back to navigating the retailer's website directly.
• Return window expired: Tell the user and suggest contacting the retailer's customer service.
• "Not eligible for return": Report to the user -- some items can't be returned through self-service.
• Page doesn't load or looks unexpected: Take a screenshot, describe what you see, and ask the user how to proceed.
• CAPTCHA / Login required: Stop and ask the user to handle it, then resume.
• QR code capture fails: Fall back to saving the full page screenshot or PDF. Note in the tracker that the user can also pull up the QR code from the confirmation email on their phone.
• PDF generation fails: Don't block the return. The markdown tracker is the source of truth.

Tips for Reliable Browser Automation

These are environment-specific examples, not required tooling. Use equivalent features in whatever browser automation stack is available.

When using Claude in Chrome (if available):

• Use read_page with filter: "interactive" to see clickable elements with refs
• Use find with natural language to locate specific elements (e.g., "Continue to return options button")
• Prefer scroll_to ref over coordinate-based scrolling — Amazon's SPA rendering frequently produces blank viewports when scrolling by pixel coordinates. Element-ref scrolling is much more reliable.
• Use form_input to set textarea/input values when type doesn't work (common on React-based forms)
• Use javascript_tool to locate elements by CSS class when find can't see them (e.g., .rufus-web-submit-button)
• Take screenshots after key actions to verify the page transitioned correctly
• If a button seems to do nothing, check for window.open interception, new tabs, or hidden modals

When using agent-browser:

• Use agent-browser snapshot -i to see interactive elements with refs, then interact using @ref notation
• Use agent-browser snapshot -c (compact) to see the full page structure including non-interactive text
• Use agent-browser eval to run JavaScript for extracting image URLs, checking element state, etc.
• Use agent-browser pdf to save pages as PDF when screenshots aren't working