feat: configurable eBay affiliate link builder #19

New issue

Closed

opened 2026-04-03 22:02:59 -07:00 by pyr0ball · 1 comment

pyr0ball commented

2026-04-03 22:02:59 -07:00

Owner

Summary

Add optional eBay Partner Network (EPN) affiliate link generation to listing click-throughs.

Design (Option B)

Add EBAY_AFFILIATE_CAMPAIGN_ID to .env.example (optional, blank by default)
If set → append EPN query params to /itm/ URLs before returning them to the frontend
If not set → return clean /itm/<id> URLs (no tracking, no affiliate revenue)
Cloud instance: CF campaign ID set in compose.cloud.yml env — users on managed instance generate revenue for CF, which is disclosed in the UI

EPN URL format

https://www.ebay.com/itm/<item_id>?mkcid=1&mkrid=711-53200-19255-0&siteid=0&campid=<CAMPAIGN_ID>&toolid=10001&mkevt=1

The scraper already normalizes to /itm/<id> — affiliate params are appended at response time, not stored.

Files to change

api/main.py — _build_listing_url(item_id) helper, called in search response serialization
.env.example — document EBAY_AFFILIATE_CAMPAIGN_ID
compose.cloud.yml — set CF campaign ID for managed instance
app/core/config.py (if snipe gets one) or read directly from os.environ

Disclosure

The frontend should surface a one-line note when affiliate links are active: "Links may include an affiliate code." This satisfies the plain-language consent principle.

## Summary Add optional eBay Partner Network (EPN) affiliate link generation to listing click-throughs. ## Design (Option B) - Add `EBAY_AFFILIATE_CAMPAIGN_ID` to `.env.example` (optional, blank by default) - If set → append EPN query params to `/itm/` URLs before returning them to the frontend - If not set → return clean `/itm/<id>` URLs (no tracking, no affiliate revenue) - Cloud instance: CF campaign ID set in `compose.cloud.yml` env — users on managed instance generate revenue for CF, which is disclosed in the UI ## EPN URL format ``` https://www.ebay.com/itm/<item_id>?mkcid=1&mkrid=711-53200-19255-0&siteid=0&campid=<CAMPAIGN_ID>&toolid=10001&mkevt=1 ``` The scraper already normalizes to `/itm/<id>` — affiliate params are appended at response time, not stored. ## Files to change - `api/main.py` — `_build_listing_url(item_id)` helper, called in search response serialization - `.env.example` — document `EBAY_AFFILIATE_CAMPAIGN_ID` - `compose.cloud.yml` — set CF campaign ID for managed instance - `app/core/config.py` (if snipe gets one) or read directly from `os.environ` ## Disclosure The frontend should surface a one-line note when affiliate links are active: "Links may include an affiliate code." This satisfies the plain-language consent principle.