eBay Browse API — Headless Access

Why this exists

The old approach scraped eBay search HTML or hit the deprecated Finding API (svcs.ebay.com). Both are dead ends. The Browse API is what eBay's own partner integrations use — richer data in one call, with proper authentication. This doc locks in the architecture so every future task and code build starts from the same place.

Hard rules

• Always Browse API. Never Finding API. Never scrape HTML unless the API is genuinely down.
• OAuth2 client_credentials only. No user-auth flows. We authenticate as the registered developer.
• Production only. The PRD prefix on credentials means real listings. Sandbox returns fake data — never useful.
• Credentials live in Cloudflare Pages secrets. Access at runtime as env.EBAY_CLIENT_ID / env.EBAY_CLIENT_SECRET. Never inline in source, never log, never expose via frontend.
• Cache the bearer token ~2h. TTL is 7200s. Refreshing every request wastes quota and adds latency.
• Quota is ~5000 calls/day. On exhaustion or 401, return empty eBay rows — never block the whole comparison flow.

Credentials & environment

Setting Pages secrets

If keys ever roll or you spin up a new Pages project that needs eBay access, set the secrets via wrangler. Never paste them into source.

npx wrangler pages secret put EBAY_CLIENT_ID --project-name always-pay-less
npx wrangler pages secret put EBAY_CLIENT_SECRET --project-name always-pay-less

Confirm they're set in the right scope:

npx wrangler pages secret list --project-name always-pay-less

Auth call (cache the token)

let _ebayTokenCache = null;

async function getEbayToken(env) {
  const now = Date.now();
  if (_ebayTokenCache && _ebayTokenCache.expiresAt > now + 60_000) {
    return _ebayTokenCache.token;
  }
  const basic = btoa(`${env.EBAY_CLIENT_ID}:${env.EBAY_CLIENT_SECRET}`);
  const r = await fetch("https://api.ebay.com/identity/v1/oauth2/token", {
    method: "POST",
    headers: {
      "Authorization": `Basic ${basic}`,
      "Content-Type": "application/x-www-form-urlencoded"
    },
    body: "grant_type=client_credentials&scope=" +
          encodeURIComponent("https://api.ebay.com/oauth/api_scope")
  });
  if (!r.ok) throw new Error(`eBay OAuth ${r.status}`);
  const data = await r.json();
  _ebayTokenCache = {
    token: data.access_token,
    expiresAt: now + (data.expires_in - 300) * 1000
  };
  return data.access_token;
}

Search call (with 401 retry)

async function searchEbayBrowse(env, query, opts = {}) {
  const { limit = 30, conditions = ["NEW"], priceMin = 10 } = opts;
  const token = await getEbayToken(env);
  const filter = [
    `price:[${priceMin}..]`,
    `priceCurrency:USD`,
    `conditions:{${conditions.join("|")}}`
  ].join(",");
  const url = `https://api.ebay.com/buy/browse/v1/item_summary/search`
            + `?q=${encodeURIComponent(query)}&limit=${limit}`
            + `&filter=${encodeURIComponent(filter)}`;
  let r = await fetch(url, {
    headers: {
      "Authorization": `Bearer ${token}`,
      "X-EBAY-C-MARKETPLACE-ID": "EBAY_US"
    }
  });
  // Token expired mid-flight — refresh once and retry
  if (r.status === 401) {
    _ebayTokenCache = null;
    const fresh = await getEbayToken(env);
    r = await fetch(url, {
      headers: {
        "Authorization": `Bearer ${fresh}`,
        "X-EBAY-C-MARKETPLACE-ID": "EBAY_US"
      }
    });
  }
  if (!r.ok) return []; // Quota exhausted or unrecoverable
  const data = await r.json();
  return (data.itemSummaries || []).map(it => ({
    title: it.title,
    price: parseFloat(it.price?.value || "0"),
    shipping: parseFloat(it.shippingOptions?.[0]?.shippingCost?.value || "0"),
    total: parseFloat(it.price?.value || "0") +
           parseFloat(it.shippingOptions?.[0]?.shippingCost?.value || "0"),
    condition: normalizeEbayCondition(it.condition, it.conditionId),
    seller: it.seller?.username,
    feedbackScore: it.seller?.feedbackScore,
    feedbackPct: it.seller?.feedbackPercentage,
    url: it.itemWebUrl,
    location: it.itemLocation?.country,
    image: it.image?.imageUrl
  }));
}

Condition ID reference

Quick CLI test

If you need to verify the keys are alive without touching the worker, run this from a terminal where the credentials are exported as env vars:

curl -s -X POST -u "$EBAY_CLIENT_ID:$EBAY_CLIENT_SECRET" \
  "https://api.ebay.com/identity/v1/oauth2/token" \
  -d "grant_type=client_credentials&scope=https://api.ebay.com/oauth/api_scope" | jq .access_token

If that returns a long bearer token string, auth is healthy. If it returns an error, check that the keys haven't rolled and that the keyset is enabled in the eBay Developer dashboard.

Diagnostics — when eBay rows come back empty

1. Check Worker logs for eBay OAuth 401 or HTTP 429 (quota).
2. Verify the Pages secrets are set in the Production scope: npx wrangler pages secret list --project-name always-pay-less.
3. Visit the eBay Developer dashboard — check today's call count against the 5000 quota.
4. Run the curl test above to confirm OAuth works outside the Worker.
5. Confirm the keyset is enabled (when first added, the keyset is disabled by default — see the eBay dev-relations confirmation email).

Why this is the right model

Open improvement

Cross-references

• Skill file (full implementation): ~/Documents/.claude/skills/ebay-browse-api/SKILL.md
• Credentials cache: ~/Documents/.claude/memory/context/api-keys.md
• Global rule entry: ~/Documents/.claude/CLAUDE.md — "eBay Browse API — Headless Access (Global Default)"
• Worker source: ~/Documents/GitHub/always-pay-less/public/_worker.js
• Cloudflare Pages project: always-pay-less · Account 8cef3a20d2c22491d2bbbc594cf4865d