Managing eBay returns
Where return cases land in CardDealer, what each action button does on the detail page, and how the audit log captures every request you send to eBay.
Last updated May 23, 2026
Managing eBay returns
eBay return cases sync into CardDealer every 5 minutes through the Post-Order API. You handle them from /orders/returns (queue) and /orders/returns/[returnId] (detail). All actions are human-clicked — CardDealer never accepts, declines, or refunds without your direct confirm.
Where returns appear
Three surfaces:
/orders/returns— dedicated queue with filter chips: Open, Awaiting response, In progress, Closed./orders/[orderId]— when the order has an active return, an "Active return" card appears at the top of the right rail with a one-click link into the detail page./ordersqueue header — when at least one return needs your attention, a coral "N returns" chip appears next to Schedule pickup + Tools.
What each action button does
The detail page's action panel exposes five buttons. Each one shows the exact JSON payload it'll POST to eBay before you confirm — read it, then click Submit. eBay's response is captured to the audit log on the way back.
| Button | Endpoint | What it does |
|---|---|---|
| Accept return | POST /return/{id}/decide | Agrees to the buyer's terms. Buyer typically ships the item back next. |
| Decline return | POST /return/{id}/decide | Refuses the case. eBay reviews if the buyer escalates — write a clear comment. |
| Issue refund | POST /return/{id}/issue_refund | Refunds the buyer in full or in part. Confirm the amount before clicking. |
| Send return label | POST /return/{id}/send_label | eBay generates a prepaid label and emails it to the buyer. |
| Mark received | POST /return/{id}/mark_returned_to_seller | Acknowledges the package arrived. Starts eBay's 2-business-day refund clock. |
The action panel's "Comments to buyer" field threads into every action's payload. Required for declines; optional but recommended elsewhere.
The audit log
Every action you take writes a row to ebay_returns_actions:
- The request you sent (full JSON payload)
- HTTP status from eBay
- Response body (full JSON, including any
errors[]) - Whether the call succeeded
- Timestamp
That row is visible inline on the return detail page under "Your actions". It's also the receipt trail if a buyer ever disputes a refund three months later — pull the log, you've got everything.
The new EU enum value
eBay introduced a new return reason on June 8, 2026: WITHDRAW_FROM_PURCHASE_CONTRACT — buyers in EU marketplaces filing under their statutory Right of Withdrawal (no fault implied).
CardDealer renders it as "Right of Withdrawal (EU)" with a sage-toned pill. The detail page adds a discreet "(EU statutory — no fault implied)" subtitle so you don't read it as a complaint.
You can still accept, decline, refund, or send a label exactly the same way as for any other reason. The enum only affects how the case is labeled in the UI.
Read-only sync vs human-clicked writes
The 5-minute sync cron is strictly read-only. It calls GET /post-order/v2/return/search and GET /post-order/v2/return/{id} — never any POST. Every state-changing action is gated behind a confirm dialog on the detail page.
This is by design: per project safety rules, eBay-modifying calls require explicit human approval. There's no setting to "auto-accept returns" or "auto-refund under $X" because there shouldn't be — every return is its own context.