--- name: Buy Amazon description: "Need to buy something from Amazon? Search products, compare prices and ratings, and place a real order shipped to any US address" homepage: https://buystuff.ai emoji: πŸ“¦ user-invocable: true tags: - shopping - buy - amazon - purchase - gift - order - delivery 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: "Used to send payment link and order updates. Not shared with third parties." - field: agentId destination: https://buystuff.ai purpose: "Optional agent identifier for order tracking. Not shared with third parties." permissions: - network: https://buystuff.ai reason: "All API calls go to buystuff.ai which proxies Amazon product data and manages orders." --- ## 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 β†’ confirm β†’ done. The user gets an email with a payment link. They pay, we ship. That's it. All API calls go to **https://buystuff.ai** β€” one endpoint, no setup, no API keys needed. ## 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 confirming an order, 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. After an order is confirmed, buystuff.ai emails the user a simple payment link. They click, pay securely on buystuff.ai, and we handle the rest β€” purchase from Amazon, ship to their door. - **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 confirming. ## Data Handling All data goes to `https://buystuff.ai` only. No third parties receive user data. | 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 | ## User Confirmation Requirement **You MUST get explicit user confirmation before confirming an order (Step 5).** Show the price breakdown, wait for "yes." No autonomous purchases. Even after confirmation, no money is charged through this API β€” the user pays via email link on their own terms. --- ## 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 `summary` with `subtotal`, `shipping`, `serviceFee`, `total`. **Agent tips:** - If the user hasn't given a shipping address, ask for it naturally: "Where should I ship it?" - If no email provided, ask: "What email should we send the payment link to?" - Always present the full breakdown before confirming: - Subtotal, Shipping (often FREE with Prime), Service fee (10%), **Total** - If the user seems surprised by the price, remind them of the 10% service fee and offer to find alternatives ## Step 5: Confirm Order `/buy-amazon-confirm` **Only call this after the user says yes.** ```bash curl -X POST https://buystuff.ai/cart/cart_abc123/confirm ``` Response returns `orderId`, `status`, `total`, and a confirmation message. Tell the user: "Check your email for the payment link β€” once you pay, we'll ship it within 24-48 hours!" ## Step 6: Track Order `/buy-amazon-status` ```bash curl "https://buystuff.ai/order/AC-MLLZVLMB-001" ``` **Statuses:** `PENDING_FULFILLMENT` β†’ `PROCESSING` β†’ `SHIPPED` β†’ `DELIVERED` When status is `SHIPPED`, there will be a `trackingNumber` β€” share it with the user. --- ## Example: Buying Earbuds ``` User: Find me wireless earbuds under $50 Agent: Here are the top wireless earbuds under $50 on Amazon: 1. πŸ† Sony WF-C500 β€” $38.00 ⭐4.5 (12,420 reviews) βœ“Prime 2. JBL Tune 130NC β€” $49.95 ⭐4.3 (8,200 reviews) βœ“Prime 3. Soundcore A20i β€” $29.99 ⭐4.4 (45,000 reviews) βœ“Prime All three have Prime (free shipping). The Sony has the best rating, and the Soundcore has the most reviews. Want details on any of these? User: Get the Sony ones. Ship to John Doe, 123 Main St, San Francisco CA 94105. Email is john@example.com Agent: Here's your order: Sony WF-C500 Wireless Earbuds $38.00 Shipping (Prime) FREE Service fee (10%) $3.80 ───────────────────────────────── Total $41.80 Ship to: John Doe, 123 Main St, San Francisco, CA 94105 Ready to confirm? User: Yes! Agent: Done! Order #AC-MLLZVLMB-001 is confirmed. πŸŽ‰ We've sent a payment link to john@example.com β€” just click, pay, and we'll ship within 24-48 hours. ``` ## Example: Birthday Gift ``` User: I need a birthday gift for my sister, she's into yoga. Budget is $30. Agent: Here are some great yoga gifts under $30 on Amazon: 1. Manduka eKO Yoga Mat Towel β€” $24.99 ⭐4.6 (3,200 reviews) βœ“Prime 2. Yoga Wheel Set (3-pack) β€” $27.95 ⭐4.5 (8,100 reviews) βœ“Prime 3. Essential Oils Gift Set β€” $19.99 ⭐4.4 (22,000 reviews) βœ“Prime πŸ”₯Deal The essential oils set is on sale and fits your budget with room to spare. The yoga wheel set is really popular. Want to see details on any? User: The yoga wheel set! Ship to Sarah Chen, 456 Oak Ave, Austin TX 78701. My email is mike@example.com Agent: Perfect gift choice! Here's the summary: Yoga Wheel Set (3-pack) $27.95 Shipping (Prime) FREE Service fee (10%) $2.80 ───────────────────────────────── Total $30.75 Ship to: Sarah Chen, 456 Oak Ave, Austin, TX 78701 Confirm? User: Do it Agent: Order #AC-MLLZVLMB-002 confirmed! 🎁 Payment link sent to mike@example.com. Pay and we'll have it shipped to Sarah within 24-48 hours. Happy birthday to your sister! ``` ## Example: Multi-Item Order ``` User: I need a wireless mouse and a mousepad for my new desk setup. Agent: Let me search for both! Here's what I found: Wireless mice: 1. Logitech M185 β€” $12.99 ⭐4.5 (75,000 reviews) βœ“Prime 2. Logitech Pebble 2 β€” $24.99 ⭐4.6 (15,000 reviews) βœ“Prime Mousepads: 1. SteelSeries QcK β€” $9.49 ⭐4.7 (90,000 reviews) βœ“Prime 2. Corsair MM350 β€” $14.99 ⭐4.6 (12,000 reviews) βœ“Prime User: Get the Logitech M185 and the SteelSeries mousepad. Agent: Added both to your cart: Logitech M185 Wireless Mouse $12.99 SteelSeries QcK Mousepad $9.49 Shipping $5.99 Service fee (10%) $2.85 ───────────────────────────────── Total $31.32 Where should I ship them? And what email for the payment link? User: Ship to Alex Kim, 789 Pine St, Seattle WA 98101. Email alex@example.com Agent: Here's the final summary: 2 items β†’ $31.32 total Ship to: Alex Kim, 789 Pine St, Seattle, WA 98101 Confirm? User: Yes Agent: Order #AC-MLLZVLMB-003 confirmed! πŸŽ‰ Payment link sent to alex@example.com. Once you pay, both items ship within 24-48 hours. ``` ## Handling Common Situations - **User doesn't give a budget:** Search normally and show a range of prices. Ask "Do you have a price range in mind?" if results vary widely. - **Product out of stock:** Say "That one's currently unavailable" and suggest similar alternatives from the search results. - **User wants to compare two products:** Pull details on both and present a quick comparison (price, rating, key specs). - **User changes their mind after checkout:** They can simply not pay the email link. The order expires if unpaid. - **User asks about returns:** Direct them to support@buystuff.ai. - **Search returns too many results:** Narrow with `sort_by`, `exclude_sponsored`, or a more specific query. ## Quick Reference ``` GET https://buystuff.ai/search?q={query} Search products GET https://buystuff.ai/product/{asin} Product details GET https://buystuff.ai/cart Get session's active cart (by session) GET https://buystuff.ai/cart/{cartId} Get cart by ID POST https://buystuff.ai/cart Add product to cart (or create cart) PATCH https://buystuff.ai/cart/{cartId}/items/{asin} Update item quantity DELETE https://buystuff.ai/cart/{cartId}/items/{asin} Remove item from cart POST https://buystuff.ai/cart/{cartId}/checkout Checkout POST https://buystuff.ai/cart/{cartId}/confirm Confirm order GET https://buystuff.ai/order/{orderId} Track order Header: X-Session-ID β€” send on all requests to maintain session ```