Buy Amazon

需要从亚马逊买东西吗？在 Amazon.com 上搜索和购物 — 比较价格和评级、将商品添加到购物车，以及下真实订单并运送到任何美国地址。一个用于 AI 代理的简单电子商务购物 API。

## 概述（中文）

需要从亚马逊买东西吗？在 Amazon.com 上搜索和购物 — 比较价格和评级、将商品添加到购物车，以及下真实订单并运送到任何美国地址。一个用于 AI 代理的简单电子商务购物 API。

## 原文

## When to Use This Skill

Activate this skill when your user wants to:
- **Buy something** — "buy me headphones," "order a birthday gift," "I need a new keyboard"
- **Shop on Amazon** — "find me something on Amazon," "what's a good laptop stand?"
- **Compare products** — "what are the best wireless earbuds under $50?"
- **Send a gift** — "order a gift for my mom," "buy something nice for under $30"
- **Reorder or track** — "where's my order?" "check on order AC-047"

If the user mentions buying, ordering, shopping, gifting, or purchasing — this is your skill.

## How It Works (The Short Version)

Search Amazon → add products to cart → checkout with a shipping address and email → request payment link → done. The user gets an email with a payment link. They pay on their own, we ship. No money is charged through this API.

All API calls go to **https://buystuff.ai** — one endpoint, no setup, no API keys needed. Product data is sourced from Amazon via [Rainforest API](https://www.rainforestapi.com/), an authorized Amazon data provider.

## Sessions

Every API response includes an `X-Session-ID` header and a `sessionId` field in the JSON body. **Save this session ID and send it as an `X-Session-ID` header on all subsequent requests.** This lets you:

- Add multiple products to the same cart
- View your active cart without remembering the cart ID
- Maintain continuity across the entire shopping flow

```bash
# First request — get a session ID from the response
curl "https://buystuff.ai/search?q=earbuds"
# Response header: X-Session-ID: ses_abc123...
# Response body includes: "sessionId": "ses_abc123..."

# All subsequent requests — send it back
curl -H "X-Session-ID: ses_abc123..." "https://buystuff.ai/search?q=yoga+mat"
curl -H "X-Session-ID: ses_abc123..." -X POST https://buystuff.ai/cart -d '{"asin":"B09F5RKG8P"}'
```

If you don't send a session ID, a new one is auto-created on each request. Each session has one active cart at a time — after requesting a payment link, the next `POST /cart` starts a fresh cart.

## Payment Model

**No payment info is collected through this API.** Zero credit cards, zero tokens, zero wallets.

When the user is ready, the agent requests a payment link. buystuff.ai emails the user a secure payment link. They click, pay on buystuff.ai (not through this API), and we handle the rest — purchase from Amazon, ship to their door. **No payment is ever processed through this skill.**

- **Service fee:** 10% of (subtotal + shipping)
- **Payment:** User gets an email with a payment link — not through this API
- **Fulfillment:** Once paid, we buy from Amazon and ship within 24-48 hours
- **Refunds:** support@buystuff.ai

Always show the full price breakdown before requesting the payment link.

## Data Handling

All API calls go to `https://buystuff.ai`. Product data is sourced via **Rainforest API**, an authorized Amazon product data provider. Shipping details are shared with Amazon only for order fulfillment. No data is sold or shared with other third parties.

| Data | When | Purpose |
|------|------|---------|
| Search queries | Step 1 | Find products (no PII) |
| Shipping address | Step 4 | Deliver the order |
| Email | Step 4 | Send payment link + updates |
| Agent ID (optional) | Step 4 | Track your agent's orders |

## Safety: No Money Charged Through This API

**This skill cannot charge money or complete purchases.** It only generates a payment link email. The user must independently open the email, review the order, and pay on buystuff.ai — completely outside this API.

You MUST get explicit user approval before requesting the payment link (Step 5). Show the price breakdown, wait for "yes." Even if the agent calls the endpoint without asking, the worst outcome is the user receives a payment link email they can simply ignore — no money is charged, no purchase is made.

---

## Step 1: Search Products

`/buy-amazon-search`

```bash
curl "https://buystuff.ai/search?q=wireless+earbuds&sort_by=price_low_to_high&number_of_results=10"
```

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `q` | string | Yes | Search query |
| `sort_by` | string | No | `price_low_to_high`, `price_high_to_low`, `average_review`, `most_recent` |
| `number_of_results` | integer | No | Limit results (default 20) |
| `exclude_sponsored` | boolean | No | Remove sponsored results |
| `page` | integer | No | Results page number |

Response includes `results[]` with `asin`, `title`, `price`, `rating`, `ratingsTotal`, `isPrime`, `isBestseller`, `isDeal`.

**Agent tips:**
- Show 3-5 results so the user can compare — don't just pick the first one
- Mention ⭐ ratings and review counts — users trust social proof
- Highlight Prime items (free shipping) and deals
- If no results found, suggest broadening the search terms or trying different keywords
- If the user has a budget, use `sort_by=price_low_to_high` and mention which ones fit

## Step 2: Check Product Details

`/buy-amazon-details`

```bash
curl "https://buystuff.ai/product/B09F5RKG8P"
```

Response includes full product info: `title`, `brand`, `price`, `buyboxWinner` (shipping cost, availability, Prime status), `rating`, `ratingBreakdown`, `specifications`, `variants`.

**Agent tips:**
- Check `buyboxWinner.availability` — if "Out of Stock," tell the user and suggest alternatives
- If `buyboxWinner.shipping.raw` is "FREE", highlight it — users love free shipping
- Show the `ratingBreakdown` percentages so users can see if ratings are legit (watch for lots of 1-stars)
- If `variants` exist (colors, sizes), ask the user which one before adding to cart
- Mention key `specifications` that match what the user asked about

## Step 3: Add to Cart

`/buy-amazon-cart`

```bash
curl -X POST https://buystuff.ai/cart \
  -H "Content-Type: application/json" \
  -H "X-Session-ID: ses_abc123..." \
  -d '{"asin": "B09F5RKG8P", "quantity": 1}'
```

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `asin` | string | Yes | Amazon product ID |
| `quantity` | integer | No | Default: 1 |

Save the `cartId` from the response — you need it for checkout.

**Multi-item carts:** Call `POST /cart` again with the same session to add more products to the same cart. If you add the same ASIN twice, the quantity is combined.

**View the current cart** (without needing the cartId):
```bash
curl -H "X-Session-ID: ses_abc123..." https://buystuff.ai/cart
```

**Update item quantity:**
```bash
curl -X PATCH https://buystuff.ai/cart/cart_abc123/items/B09F5RKG8P \
  -H "Content-Type: application/json" \
  -d '{"quantity": 3}'
```

**Remove an item:**
```bash
curl -X DELETE https://buystuff.ai/cart/cart_abc123/items/B09F5RKG8P
```

**If adding fails:** The ASIN might be invalid or the product unavailable. Go back to search and help the user pick another option.

## Step 4: Checkout

`/buy-amazon-checkout`

```bash
curl -X POST https://buystuff.ai/cart/cart_abc123/checkout \
  -H "Content-Type: application/json" \
  -d '{
    "shipping": {
      "name": "John Doe",
      "line1": "123 Main St",
      "line2": "Apt 4B",
      "city": "San Francisco",
      "state": "CA",
      "zip": "94105",
      "country": "US"
    },
    "email": "john@example.com",
    "agentId": "your-agent-id"
  }'
```

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `shipping.name` | string | Yes | Recipient full name |
| `shipping.line1` | string | Yes | Street address |
| `shipping.line2` | string | No | Apt, suite, unit |
| `shipping.city` | string | Yes | City |
| `shipping.state` | string | Yes | 2-letter state code |
| `shipping.zip` | string | Yes | ZIP code |
| `shipping.country` | string | No | Default: "US" |
| `email` | string | Yes | For payment link + order updates |
| `agentId` | string | No | Your agent ID |

Response returns `su