pyr0ball opened issue Circuit-Forge/snipe#19

pyr0ball
Fri, 03 Apr 2026 22:02:59 -0700

19#feat: configurable eBay affiliate link builder#

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.