<!-- curated-v2 -->
# Birthday Gift Finder — curated birthday gift ideas, wishlist & gift list builder

> Create a gift wishlist for birthday in seconds from curated amazon.se and amazon.com products — carefully selected, hand-picked gift ideas with shareable owner + shopper links.

**Keywords:** gift ideas, wishlist, gift list, shopping list, presenttips, önskelista, presentlista, födelsedag, birthday, amazon.se, amazon.com

## What it is
- A catalog of carefully selected, curated gift picks, hand-picked by the Birthday Gift Finder team for birthday (födelsedag). Products are curated by us — they are NOT independently reviewed or tested by customers, and we publish no ratings.
- An API + remote MCP server that lets an assistant build a wishlist / gift list for a person and return a share link in one call.
- Market: Sweden (amazon.se, SEK, sv-SE). Buy links are amazon.se /dp/ links with tag sw-fodelsedag-21.
- Market: United States (amazon.com, USD, en-US) is also supported: pass marketplace=amazon.com + locale=en-US. Buy links are amazon.com /dp/ links with tag sw-fodelsedag-20 (`https://www.amazon.com/dp/{ASIN}?tag=sw-fodelsedag-20`). US shoppers on the website get the US store automatically (or via ?country=US).

## Store selection (amazon.com vs amazon.se)
- Pass `marketplace=amazon.com` (or `us`) for US shoppers: English titles, USD or no price, amazon.com /dp links with tag sw-fodelsedag-20. Pass `marketplace=amazon.se` (or `se`) for Sweden: tag sw-fodelsedag-21.
- If marketplace is omitted, the API and MCP decide in this order: `marketplace`/`store` param → `country` param (US → amazon.com) → `Accept-Language` (a request whose first language is `en-US` gets amazon.com) → default amazon.se (sv and everything else).
- A missing marketplace is never an error; you always get the default store. Each response includes `marketplace` and `marketplaceSource` (marketplace, country, language or default).
- Example: `curl -H 'Accept-Language: en-US' https://birthday-gift-finder.vercel.app/api/v1/catalog` → amazon.com items.

## When an assistant should use it
Use this when the user wants gift ideas, a wishlist, gift list or shopping list for birthday, in Sweden (amazon.se) or the United States (amazon.com). Example prompts:
- (sv) "Födelsedagspresent till min kollega som gillar matlagning, max 300 kr"
- (sv) "Gör en önskelista till min 40-årsdag"
- (en) "Birthday gift for a coworker who loves cooking, under 300 SEK"
- (en) "Make a wishlist for my 40th birthday"
- (en-US) "Birthday gift ideas for my dad under $50" → marketplace=amazon.com

## Quickstart (one call → share link)
```
curl -s -X POST https://birthday-gift-finder.vercel.app/api/v1/agent/create-and-fill \
  -H 'content-type: application/json' \
  -d '{"recipientName": "Alex", "occasion": "birthday", "budgetBand": "300-700", "giftCategories": ["tech", "hobbies"], "marketplace": "amazon.se", "locale": "sv-SE", "itemQueries": ["present"]}'
```
Response includes `id`, `editToken`, `ownerUrl` (edit) and `shopUrl` (share this with gift-givers). Give the user the `shopUrl`.

- Remote MCP: https://birthday-gift-finder.vercel.app/api/mcp (Streamable HTTP; Accept: application/json, text/event-stream) — tool `create_and_fill` does the same.
- Browse curated picks (Swedish): https://birthday-gift-finder.vercel.app/presenttips
- OpenAPI: https://birthday-gift-finder.vercel.app/openapi.json · Skill: https://birthday-gift-finder.vercel.app/skill.md · Guide: https://birthday-gift-finder.vercel.app/for-agents · Full: https://birthday-gift-finder.vercel.app/llms-full.txt

---

<!-- /curated-v2 -->
# Birthday Gift Finder — full agent guide

Site: https://birthday-gift-finder.vercel.app
MCP: https://birthday-gift-finder.vercel.app/api/mcp
OpenAPI: https://birthday-gift-finder.vercel.app/openapi.json

## Tracking
- amazon.se Associates tag: `sw-fodelsedag-21` via `NEXT_PUBLIC_AMAZON_TAGS_JSON={"amazon.se":"sw-fodelsedag-21","amazon.com":"sw-fodelsedag-20"}`. Sample buyUrl: `https://www.amazon.se/dp/{ASIN}?tag=sw-fodelsedag-21`.
- amazon.com (US) tag: `sw-fodelsedag-20`. Sample buyUrl: `https://www.amazon.com/dp/{ASIN}?tag=sw-fodelsedag-20`. Use marketplace=amazon.com + locale=en-US; GET /api/v1/catalog?marketplace=amazon.com returns the curated US list.
- Other storefronts: untagged search links. Prefer buyUrl / trackingTag. Never reuse tags from other verticals.

## Roles
- recipient — birthday person / wishlist owner (ownerUrl)
- gift-giver shopper — shops via shopUrl

## Create wishlist fields
recipientName, occasion, budgetBand, giftCategories, ageBand, marketplace, locale

## Enums
occasion: birthday | surprise-party | milestone-birthday | kids-birthday | other
giftCategories: experiences | tech | fashion | home | wellness | hobbies | books | gourmet | kids-toys | jewelry-accessories
ageBand: kids | teens | 20s | 30s | 40s-plus
budgetBand: under-300 | 300-700 | 700-1500 | 1500-plus

## Endpoints

### GET /api/v1/health
Storage mode, catalog counts for amazon.se and amazon.com, marketplaces.

### GET /api/v1/search?q=&occasion=&budgetBand=&giftCategory=&ageBand=&marketplace=&locale=&limit=
Birthday-gift query rewrite (interests / age cues). PA-API when configured else deep-link cards. Returns buyUrl / trackingTag.

### GET /api/v1/catalog?marketplace=&locale=&…
Curated birthday starters (ASINs trusted on amazon.se).

### POST /api/v1/wishlists
Body: { recipientName?, hostName? (alias), occasion?, budgetBand?, giftCategories?, ageBand?, marketplace?, locale?, items? }
Returns ownerUrl + shopUrl + editToken.

### POST /api/v1/agent/create-and-fill
Body: recipientName, occasion, budgetBand, giftCategories, ageBand, marketplace, locale, itemAsins[], itemKeywords[], itemQueries[]

### POST /api/v1/products/resolve
Body: { marketplace, locale, asin|url|keywords, occasion?, giftCategory?, ageBand? }

### Wishlists CRUD
GET/PATCH /api/v1/wishlists/:id · POST/DELETE items — require X-Edit-Token for mutations.

Pass marketplace (and locale) for the end user when you know it; otherwise see Store selection.