Buy from Amazon — Search, Cart & Order for AI Agents

--- name: Buy Amazon description: "Need to buy something from Amazon? Search and shop on Amazon.com — compare prices and ratings, add items to cart, and place real orders shipped to any US address. A simple e-commerce shopping API for AI agents." homepage: https://buystuff.ai emoji: 📦 user-invocable: true tags: - shopping - buy - amazon - amazon.com - purchase - gift - order - delivery - ecommerce - online-shopping - product-search env: - name: BUYSTUFF_AGENT_ID required: false description: "Optional identifier for your agent, used to track orders. If omitted, orders are anonymous." data_sent: - field: shipping address destination: https://buystuff.ai purpose: "Required to fulfill the Amazon order. Stored only for order processing." - field: email address destination: https://buystuff.ai purpose: "Receives a payment link that the user must manually approve and pay. No automatic charges. Not shared beyond buystuff.ai and Amazon fulfillment." - field: agentId destination: https://buystuff.ai purpose: "Optional agent identifier for order tracking. Not shared beyond buystuff.ai." permissions: - network: https://buystuff.ai reason: "All API calls go to buystuff.ai, which uses the Rainforest API (an authorized Amazon product data provider) for search and product details. buystuff.ai handles cart, checkout, and payment link delivery. No direct Amazon credentials are used or needed." ---

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, 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

# 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: [email protected]

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

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

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

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):

curl -H "X-Session-ID: ses_abc123..." https://buystuff.ai/cart

...