BuyWhere
← Back to documentation

day7

BuyWhere Day 7 — Agent Integration Examples + Support

One week in. Time to wire BuyWhere into your AI agent workflow for real commerce tasks.

Core Agent Patterns

Product Research → Purchase Flow

import os
import requests
from langchain_core.tools import tool

BUYWHERE_API_KEY = os.environ["BUYWHERE_API_KEY"]
BUYWHERE_BASE_URL = "https://api.buywhere.ai"

@tool
def buywhere_search(query: str, limit: int = 5) -> str:
    """Search BuyWhere products and return top results."""
    response = requests.get(
        f"{BUYWHERE_BASE_URL}/v1/products",
        headers={"Authorization": f"Bearer {BUYWHERE_API_KEY}"},
        params={"q": query, "limit": limit},
        timeout=30,
    )
    response.raise_for_status()
    items = response.json().get("items", [])
    if not items:
        return f"No results for {query!r}."
    lines = []
    for item in items:
        link = item.get("affiliate_url") or item.get("buy_url")
        lines.append(
            f"{item['name']} | {item['currency']} {item['price']} | "
            f"{item['source']} | {link}"
        )
    return "\n".join(lines)

@tool
def buywhere_best_price(product_name: str) -> str:
    """Find the cheapest BuyWhere listing for a product."""
    response = requests.get(
        f"{BUYWHERE_BASE_URL}/v1/products/best-price",
        headers={"Authorization": f"Bearer {BUYWHERE_API_KEY}"},
        params={"q": product_name},
        timeout=30,
    )
    response.raise_for_status()
    item = response.json()
    link = item.get("affiliate_url") or item.get("buy_url")
    return (
        f"{item['name']} | {item['currency']} {item['price']} | "
        f"{item['source']} | {link}"
    )

Multi-Step Buying Agent (CrewAI)

from crewai import Agent, Task, Crew
from langchain_core.tools import tool

@tool("buywhere_search")
def buywhere_search(query: str) -> str:
    ...

@tool("buywhere_best_price")
def buywhere_best_price(product_name: str) -> str:
    ...

researcher = Agent(
    role="Price Researcher",
    goal="Find the best deals across Singapore e-commerce",
    tools=[buywhere_search, buywhere_best_price],
)

task = Task(
    description="Research and compare prices for a Sony WH-1000XM5 across all sources",
    agent=researcher,
)

crew = Crew(agents=[researcher], tasks=[task])
result = crew.kickoff()

Price Comparison Agent

import requests

def compare_price(product: str) -> str:
    response = requests.get(
        f"{BUYWHERE_BASE_URL}/v1/products/compare",
        headers={"Authorization": f"Bearer {BUYWHERE_API_KEY}"},
        params={"q": product},
        timeout=30,
    )
    data = response.json()
    # data["items"] contains price across multiple sources
    rows = []
    for item in data.get("items", []):
        rows.append(f"{item['source']}: {item['currency']} {item['price']}")
    return "\n".join(rows)

Error Handling

import requests

def safe_search(query: str, limit: int = 5) -> dict:
    try:
        response = requests.get(
            f"{BUYWHERE_BASE_URL}/v1/products",
            headers={"Authorization": f"Bearer {BUYWHERE_API_KEY}"},
            params={"q": query, "limit": limit},
            timeout=30,
        )
        response.raise_for_status()
        return {"success": True, "data": response.json()}
    except requests.exceptions.HTTPError as e:
        if e.response.status_code == 429:
            return {"success": False, "error": "Rate limited — back off and retry"}
        return {"success": False, "error": str(e)}
    except requests.exceptions.Timeout:
        return {"success": False, "error": "Request timed out"}

Rate Limits

  • Developer beta access is free, with rate limits applied per API key.
  • If you hit a 429, back off and retry after the Retry-After window.
  • If your agent is driving meaningful production-like traffic, reply with your use case and current request volume to ask for a higher beta limit.

See full rate limit docs at https://api.buywhere.ai/docs/rate-limits

Support Channels

SDK Repos

  • Python: buywhere (pip) + source at /home/paperclip/buywhere-py
  • JS/TS: @buywhere/sdk (npm)
  • LangChain tools built into Python SDK

Happy building!