eBay Sell API integration for pa.gf.cx/ebay-seller — parked sketch
Date: 2026-05-20 · Surface: pa.gf.cx/ebay-seller/ · Status: Parked — manual ledger is fine for now; resume when listing volume justifies
Dan, 2026-05-20:
“park as sketch with resume conditions, fascinating idea”
This sketch captures the eBay API integration path so we can return to it cleanly when the conditions are right. The current /ebay-seller page is manually maintained (one transaction logged today — the $35 PayPal refund). When listings reach a threshold or payout reconciliation becomes load-bearing, this is the build to pull off the shelf.
The opportunity
eBay offers a comprehensive Sell APIs suite (modern OAuth 2.0) that maps cleanly onto every section the /ebay-seller page currently stubs:
/ebay-seller section |
eBay API endpoint |
|---|---|
| Active listings | Sell Inventory API — getInventoryItems, listing status, prices, quantities, descriptions, photos |
| Sales / orders | Sell Fulfillment API — getOrders, shipment state, buyer info, item titles, ship dates |
| Payouts & fees | Sell Finances API — getPayouts, getTransactions (fees, sales, refunds), payout schedule, gross-to-net reconciliation |
| Disputes & cases | Post-Order API — returns, INRs (Item Not Received), money-back-guarantee cases, refund requests |
| Account identity | Sell Account API — user info, payment policies, shipping policies, store info |
Bonus — APIs we’d reach for as the page grows: - Browse API — public-facing item lookup if Dan ever wants to embed listings on dare or audrey - Marketing API — promoted listings + campaigns (probably not needed for offload-only use case) - Compliance API — listing violation checks if eBay flags something
The architecture sketch (mirrors today’s gsc_pull.py pattern)
The same shape that worked for GSC integration today:
STASH9
Sibling memory: this exactly mirrors what gsc_pull.py does for the dare GSC data + how dare_session_report.py renders MD to HTML. The pattern is portable; the API is the only new piece.
OAuth flow specifics (mirror of today’s GSC OAuth setup)
- Developer registration at developer.ebay.com — free, ~10 min, gets: - App ID (Client ID) - Dev ID - Cert ID (Client Secret)
- OAuth user-consent dance — Dan grants the app access to his eBay seller account
- Redirect to
auth.ebay.com/oauth2/authorizewith scopes - Auth code back → exchange for refresh token (lasts 18 months) - Refresh token stored in 1Password as custom-named concealed field (perfeedback_1password_custom_concealed_fields.md) — name suggestion:ebay_seller_refresh_token - Per-request flow — exchange refresh → short-lived access token (2hr) → API call
Scopes needed for the full integration:
- https://api.ebay.com/oauth/api_scope/sell.inventory.readonly
- https://api.ebay.com/oauth/api_scope/sell.fulfillment.readonly
- https://api.ebay.com/oauth/api_scope/sell.finances
- https://api.ebay.com/oauth/api_scope/sell.account.readonly
All read-only except finances (which needs write scope only if we want to issue refunds via the API — today’s PayPal-direct refund didn’t go through eBay’s flow, so read-only finances is probably enough for v1).
Cost shape
| Item | Cost |
|---|---|
| Developer account | $0 (free for individual sellers) |
| API calls (production) | $0 within rate limits |
| Sandbox calls | $0 unlimited |
| Storage of pulled JSON | negligible (< 1 MB/day per category) |
| Total | $0 |
Rate limits (per API, per day)
Individual seller account typical limits — comfortable for a one-person offload operation:
| API | Daily limit | Typical use |
|---|---|---|
| Sell Inventory | 5,000 calls | List sync — ~1 call/day pulls everything |
| Sell Fulfillment | 25,000 calls | Order history — ~5-20 calls/day |
| Sell Finances | 5,000 calls | Payout + transaction pulls — ~5 calls/day |
| Sell Account | 5,000 calls | Rarely needed — 1 call/week max |
Total daily call budget: < 50 calls. Limit headroom: ~99.9%.
The catch — production API approval
This is the one piece of friction worth knowing about ahead of time:
- Sandbox access is immediate after developer signup — unlimited, fake data
- Production access for SOME endpoints (especially Sell Finances + Sell Fulfillment with PII) requires “Production Application Keys” approval
- Submit app description to eBay, takes hours to days
- Usually approved for a legitimate seller-tools use case
- Once approved, no further review per call
- Strategy: build + test in sandbox, then submit for production review as Phase B
Phase A build (when triggered)
Effort estimate: ~3-4 hours active work spread across two sessions.
| Step | Effort | Detail |
|---|---|---|
| 1. Developer registration + sandbox app | 30 min | developer.ebay.com signup + create sandbox app |
| 2. OAuth dance scaffolding | 60 min | ~/bin/ebay_oauth_setup.py — one-shot Auth Code grant + refresh token capture |
| 3. 1Password storage of credentials | 10 min | App ID, Cert ID, refresh token — custom-named concealed fields per discipline |
4. ebay_pull.py — basic pull (sandbox) |
90 min | Inventory + Orders + Finances; markdown output |
5. ebay_seller_render.py |
60 min | MD → templated HTML; preserves manual records |
| 6. Test against sandbox; deploy to pa.gf.cx | 30 min | wrangler deploy chain (same as today’s cycle) |
| 7. Submit for production keys | 15 min | App description + use case to eBay |
Phase B: ~2 hours once production keys land — swap sandbox endpoints for prod, smoke-test, cron schedule.
Revenue baseline (Dan, 2026-05-20)
“We are doing about $3000 per year on ebay”
| Metric | Estimate at $3k/year |
|---|---|
| Gross monthly | ~$250 |
| Average sale (estimated) | $20-50 |
| Transactions per month | ~5-12 |
| Transactions per year | ~60-150 |
| Active listings at any moment | ~3-15 (depends on turnover) |
| Payouts per month | ~1-2 |
What this means for the build trigger: at this volume the API integration is already worth the build cost in attention saved. The blocker isn’t whether it’s worth it — it’s whether the cumulative friction from manual entry has hit Dan’s “annoying enough to fix” threshold. Watch for: - Explicit complaints about manual entry overhead - Desire for a month-end summary that doesn’t exist today (gross sales · fees · net · YoY) - Wanting tax-time consolidated CSV without going to eBay’s UI
The original “≥10 active listings” threshold from below was set before the revenue baseline came in. With $3k/year already on the table, the active-listing count isn’t the gating signal — operator friction is.
Resume conditions
Build Phase A when any of these hold:
- Listing volume reaches ~10+ active items — manual ledger becomes annoying to maintain
- Payout reconciliation matters — Dan wants to see “you sold $X, paid $Y in fees, netted $Z this month” automatically vs spreadsheeting it
- A second eBay-style integration becomes interesting — Etsy / Mercari / Poshmark / Reverb — building the eBay integration is a template for those (same OAuth-pull-render shape)
- Tax season — auto-export of all transactions as CSV for Schedule C or 1099-K reconciliation
- Dispute volume — if returns/cases happen often enough that manual logging misses some, the API guarantees no gaps
Skip / defer if: - Inventory stays under ~5 items - Each transaction is unique enough that manual capture is more useful than auto-pull (you write context the API doesn’t capture — like the dual-LLC observation from today’s Zelle entry) - Tax season is handled by the eBay-provided dashboard exports
Sibling memories + projects
feedback_1password_custom_concealed_fields.md— token storage discipline (ebay_seller_refresh_tokenas custom-named field, not default password slot)feedback_sentinel_based_op_injection.md— re-exec pattern for credential injection (use forebay_pull.py)feedback_check_devreports_before_infra_gap_analysis.md— when resuming this, check~/bin/ebay_*+~/Downloads/ebay_seller_*firstproject_gsc_three_property_baseline.md— the GSC integration this design mirrorsfeedback_short_alias_redirects_proactive.md— already shipped/ebay → /ebay-seller/; the API would only enrich what/ebay-seller/shows- Today’s pa.gf.cx work (commits
910ad48+1818090+c6d3991) — the surface this would feed feedback_state_emerges_from_data.md— when the API lands, the page state (NEW listing badges, “just sold” markers, etc.) should derive from the pulled data, not be flagged manually
The aphorism
The first time it’s manual. The third time it’s an API. eBay is at one — we’ll know when it’s three.