BuyWhere
← Back to documentation

developer-copy-pack

BuyWhere API Developer Copy Pack

Issue: BUY-2541 Purpose: Homepage, quickstart, and use-case copy for the developer-facing documentation site

1. Homepage Copy

1.1 Hero Section

Headline (Option A — Developer-First):

Build AI Shopping Agents That Actually Buy

Subhead:

The agent-native product catalog API. Search, compare, and track prices across 10,000+ merchants in Singapore and Southeast Asia — with a single API call.

Headline (Option B — Simplicity-First):

One API. Every Product. Zero Friction.

Subhead:

BuyWhere gives AI agents the product data they need — live prices, stock availability, and affiliate-tracked purchase links across Lazada, Shopee, Carousell, Amazon, and 50+ more platforms.

Recommended: Option A — targets the AI agent developer persona directly

Primary CTA: [Get API Key] | [Read the Docs]

Social Proof Line:

Trusted by developers building the next generation of AI commerce

1.2 Quick Links Section

Card 1: Quickstart

  • Title: Get Started in 5 Minutes
  • Body: From zero to your first API call. No credit card required.
  • CTA: Start Building →

Card 2: API Reference

  • Title: Complete API Reference
  • Body: Every endpoint, parameter, and response schema — with live examples in Python, JavaScript, Go, and curl.
  • CTA: Browse Endpoints →

Card 3: SDKs & Libraries

  • Title: Official SDKs
  • Body: Python, JavaScript/TypeScript, Go, Ruby. LangChain and CrewAI integrations included.
  • CTA: View SDKs →

Card 4: Code Examples

  • Title: Working Examples
  • Body: Full implementations for price comparison agents, deal alert bots, and shopping research crews.
  • CTA: See Examples →

1.3 Featured Guides Section

Guide 1: AI Agent Integration

  • Title: Building AI Shopping Agents with BuyWhere
  • Description: Integrate product search, price comparison, and deal discovery into your agent stack — with LangChain, CrewAI, and MCP examples.
  • CTA: Read Guide →

Guide 2: Price Comparison Agent

  • Description: Use the /compare endpoint to build a workflow that finds the cheapest listing for any product across all Singapore retailers.
  • CTA: Build It →

Guide 3: Deal Alert Bot

  • Description: Create a Telegram or Discord bot that monitors price drops and alerts your users when products hit their target price.
  • CTA: Create Bot →

1.4 Trust / Stats Bar

Stats to highlight:

  • 80,000+ products indexed
  • 50+ merchant sources
  • 99.9% uptime SLA
  • < 200ms average latency

Trust badges/copy:

"We don't sell products. We compare them — with no retailer favoritism." Affiliate disclosure: We earn commissions on purchases, but this never affects rankings.

2. Quickstart Copy

2.1 Prerequisites Block

What you need:
- A BuyWhere API key (get one at developers.buywhere.com)
- curl or any HTTP client
- Python 3.10+ (optional, for SDK examples)

2.2 Step-by-Step Copy

Step 1: Verify your setup

First, let's confirm your API key works. Run:

curl https://api.buywhere.ai/health

You should see: {"status": "ok"}

Step 2: Make your first search

Now search for a real product:

curl "https://api.buywhere.ai/v1/products?q=wireless+headphones&limit=3" \
  -H "X-API-Key: YOUR_API_KEY"

Step 3: Understand the response

Key fields in every product response:

  • name — product title
  • price + currency — current price
  • source — which merchant (shopee_sg, lazada_sg, etc.)
  • affiliate_url — tracked link for commissions

Step 4: Find the best price

One query to find the cheapest listing:

curl "https://api.buywhere.ai/v1/products/best-price?q=sony+wh-1000xm5" \
  -H "X-API-Key: YOUR_API_KEY"

2.3 What's Next Block

You've made your first API call. Now explore:

3. Use-Case Snippets

3.1 Price Comparison Agent

Title: Find the Cheapest Listing Across All Platforms

The problem:

"I want to find the best price for a PS5 bundle across Singapore retailers."

The solution:

from buywhere_sdk import BuyWhere

client = BuyWhere(api_key="bw_live_xxxxx")

# Search for the product
results = client.search("playstation 5 bundle", limit=5)

# Get the top result
product = results.items[0]

# Find all listings across platforms
comparison = client.get(f"/v1/products/compare?product_id={product.id}")

# Sort by price
matches = sorted(comparison['matches'], key=lambda x: x['price'])

print(f"Best deal: {matches[0]['source']} at SGD {matches[0]['price']}")
print(f"Save {comparison['savings_pct']}% vs most expensive option")

Why this works for agents:

  • Single tool call to best_price for simple queries
  • Full comparison data for complex purchase decisions
  • Affiliate links included for commission tracking

3.2 Deal Alert Bot

Title: Notify Users When Prices Drop

The problem:

"I want to build a bot that watches product prices and alerts my users when something goes on sale."

The solution:

from buywhere_sdk import BuyWhere

client = BuyWhere(api_key="bw_live_xxxxx")

def check_deals(category="Electronics", min_discount=30):
    deals = client.get_deals(
        category=category,
        min_discount_pct=min_discount,
        limit=10
    )
    
    for deal in deals.deals:
        message = f"""
🔥 DEAL ALERT: {deal.name}
💰 {deal.currency} {deal.price} (was {deal.original_price})
📉 {deal.discount_pct}% off | {deal.source}
⭐ Rating: {deal.rating}/5 ({deal.review_count} reviews)
🔗 {deal.buy_url}
        """
        # Send to Telegram, Discord, Slack, etc.
        send_notification(message)

# Run every 5 minutes
while True:
    check_deals()
    time.sleep(300)

Why this works for agents:

  • /v1/deals endpoint returns current discounts in real-time
  • Filter by category, discount percentage, merchant
  • Affiliate links included for monetization

3.3 Shopping Research Crew

Title: Multi-Agent Research + Comparison Workflow

The problem:

"I want an AI crew where one agent researches products and another identifies the best value."

The solution:

from crewai import Agent, Task, Crew
from buywhere_sdk import BuyWhere

client = BuyWhere(api_key="bw_live_xxxxx")

researcher = Agent(
    role="Product Researcher",
    goal="Find all relevant products for the user's shopping request",
    backstory="Expert at finding products across Singapore e-commerce platforms"
)

comparer = Agent(
    role="Price Comparer", 
    goal="Identify the best value from a list of products",
    backstory="Expert at evaluating product value and finding the lowest price"
)

def search_task(query: str):
    results = client.search(query, limit=20)
    return "\n".join([
        f"{p.name} | {p.currency} {p.price} | {p.source} | {p.buy_url}"
        for p in results.items
    ])

def compare_task(product_list: str):
    # Parse prices and find minimum
    lines = [l for l in product_list.strip().split("\n") if l]
    best = min(lines, key=lambda l: float(l.split("|")[1].strip().replace("SGD ", "")))
    return f"Best deal: {best}"

research = Task(
    description="Search for: Nintendo Switch OLED",
    agent=researcher,
    function=search_task
)

comparison = Task(
    description="From the product list, identify the best price",
    agent=comparer,
    function=compare_task
)

crew = Crew(agents=[researcher, comparer], tasks=[research, comparison])
result = crew.kickoff(inputs={"query": "Nintendo Switch OLED"})

Why this works for agents:

  • search() returns structured product data for easy parsing
  • best_price() for one-step cheapest listing
  • Multi-currency support for cross-border shopping

3.4 Price Tracking Dashboard

Title: Monitor Wishlist Prices Over Time

The problem:

"I want to track prices for products on my user's wishlist and show them when to buy."

The solution:

from buywhere_sdk import BuyWhere

client = BuyWhere(api_key="bw_live_xxxxx")

wishlist = [
    {"query": "Sony WH-1000XM5", "target": 300},
    {"query": "iPad Air 256GB", "target": 700},
    {"query": "Nintendo Switch OLED", "target": 350},
]

def check_wishlist():
    report = []
    for item in wishlist:
        # Find current price
        product = client.best_price(item["query"])
        
        # Check against target
        if product.price <= item["target"]:
            report.append(f"✅ BUY NOW: {product.name} at SGD {product.price}")
        else:
            # Get price prediction
            stats = client.get_price_stats(product.id)
            report.append(f"⏳ {product.name}: SGD {product.price} (target: SGD {item['target']})")
    
    return "\n".join(report)

print(check_wishlist())

Why this works for agents:

  • best_price() for quick lookup
  • get_price_stats() for 30-day price history
  • get_price_prediction() for forward pricing

3.5 MCP Integration (Claude Desktop)

Title: Give Claude Direct Access to Product Data

The problem:

"I want Claude to look up product prices and compare options as part of a conversation."

The solution:

  1. Install the BuyWhere MCP server:
git clone https://github.com/buywhere/buywhere-mcp.git
cd buywhere-mcp && npm install && npm run build
  1. Add to Claude Desktop config:
{
  "mcpServers": {
    "buywhere": {
      "command": "node",
      "args": ["/path/to/buywhere-mcp/dist/index.js"],
      "env": {
        "BUYWHERE_API_KEY": "bw_live_xxxxx"
      }
    }
  }
}
  1. Claude can now use these tools:
  • search_products — find products by keyword
  • get_product — get full product details
  • compare_prices — cross-platform comparison
  • get_deals — current discounts

Example conversation:

User: Find me the cheapest PS5 bundle in Singapore Claude: I'll search across all retailers to find the best price. [uses search_products and compare_prices] Claude: The best deal is SGD 569 at Shopee, including the game bundle. Would you like me to compare it with other retailers?

4. Error State Copy

API Errors

401 Unauthorized:

Your API key is missing or invalid. Get a key at developers.buywhere.com and include it as X-API-Key: YOUR_KEY.

404 Not Found:

No products match your query. Try a more general search term, or browse by category.

429 Rate Limited:

You've hit your request limit. Wait a moment and try again, or upgrade your plan for higher limits.

500 Server Error:

Something went wrong on our end. This is usually temporary — try again in a few seconds.

Empty States

No search results:

No products found for "[query]". Try adjusting your search or browse categories.

No deals in category:

No deals currently available in [category]. Check back later — deals update hourly.

Product unavailable:

This product appears to be out of stock everywhere. Set a price alert and we'll notify you when it's back.

5. CTA Copy Variants

Primary CTAs (Conversion-Focused)

  • Get API Key — Start building now
  • Read the Docs — Learn the API
  • View on GitHub — See the source
  • Try the Demo — Test without signing up

Secondary CTAs (Education-Focused)

  • See Pricing — Understand costs
  • Contact Sales — Enterprise inquiries
  • Join Discord — Community support
  • Read the Blog — Updates and guides

Contextual CTAs

After successful search:

Ready to build? Get an API Key or explore the SDK.

After rate limit:

Need higher limits? Compare plans or contact sales.

Empty search results:

Can't find what you're looking for? Browse categories or set a price alert.

6. Microcopy Reference

Loading States

  • "Searching across 50+ retailers..."
  • "Comparing prices..."
  • "Finding the best deal..."
  • "Checking availability..."

Confirmation Messages

  • "Price alert set. We'll notify you at [email]."
  • "Your API key is ready. Copy it now — we won't show it again."
  • "Product added to your watchlist."

Tool Descriptions (for LangChain/MCP)

search_products:

Search for products by keyword. Returns top matches with prices, ratings, and purchase links.

get_best_price:

Find the cheapest listing for a product across all Singapore e-commerce platforms.

compare_prices:

Compare the same product across multiple retailers. Shows price, shipping, delivery time, and seller rating.

get_deals:

Find products currently on sale. Filter by category, discount percentage, or merchant.

track_click:

Record a product click for analytics. Returns the affiliate redirect URL.

7. Tone & Voice Guidelines

Do

  • Be direct — get to the point, developers are busy
  • Show code — working examples over long explanations
  • Be specific — "SGD 569" beats "good price"
  • Be honest — disclose affiliate relationships upfront

Don't

  • Don't be salesy — "revolutionary", "game-changing", "best-in-class"
  • Don't be vague — "leverage synergies" → "use the API"
  • Don't apologize excessively — "sorry, we couldn't find" → "no results found"
  • Don't assume — don't assume Singapore-only or English-only

Voice Attributes

  • Confident but humble — "Our API is fast" not "the fastest API ever"
  • Technical but accessible — assume developer audience, explain domain terms
  • Helpful over clever — clear beats witty for documentation