devsoul2026/hermes-one-click/shop-app

Shop.app — Personal Shopping Assistant

Use this skill when the user wants to search products across stores, compare prices, find similar items, track an order, manage a return, or re-order a past purchase through Shop.app's agent API.

No auth required for product search. Auth (device-authorization flow) is required for any per-user operation: orders, tracking, returns, reorder. Store tokens only in your working memory for the current session — never write them to disk, never ask the user to paste them.

All endpoints return plain-text markdown (including errors, which look like # Error\n\n{message} ({status})). Use curl via the terminal tool; for the try-on feature use the image_generate tool.

Product Search (no auth)

Endpoint: GET https://shop.app/agents/search

curl -s 'https://shop.app/agents/search?query=wireless+earbuds&limit=10&ships_to=US'

Response format: Plain text. Products separated by \n\n---\n\n.

Fields to extract per product:

• Title — first line
• Price + Brand + Rating — second line ($PRICE at BRAND — RATING)
• Product URL — line starting with https://
• Image URL — line starting with Img:
• Product ID — line starting with id:
• Variant IDs — in the Variants section or from the variant= query param in the product URL
• Checkout URL — line starting with Checkout: (contains {id} placeholder; replace with a real variant ID)

Pagination: none. For more or different results, vary the query (different keywords, synonyms, narrower/broader terms). Up to ~3 search rounds.

Errors: missing/empty query returns # Error\n\nquery is missing (400).

Find Similar Products

Same response format as Product Search.

By variant ID (GET):

curl -s 'https://shop.app/agents/search?variant_id=33169831854160&limit=10&ships_to=US'

The variant_id must come from the variant= query param in a product URL — the id: field from search results is not accepted.

By image (POST):

curl -s -X POST https://shop.app/agents/search \
  -H 'Content-Type: application/json' \
  -d '{"similarTo":{"media":{"contentType":"image/jpeg","base64":"<BASE64>"}},"limit":10}'

Requires base64-encoded image bytes. URLs are not accepted — download the image first (curl -o), then base64 -w0 file.jpg to inline.

Authentication — Device Authorization Flow (RFC 8628)

Required for orders, tracking, returns, reorder. Not required for product search.

Session state (hold in your reasoning context for this conversation only):

Rules:

• user_code is always 8 chars A-Z, formatted XXXXXXXX.
• No client_id, client_secret, or callback needed — the proxy handles it.
• Never ask the user to paste tokens into chat.
• Tokens live only for the duration of this conversation. Do not write them to .env or any file.

Flow

1. Request a device code:

curl -s -X POST https://shop.app/agents/auth/device-code

Response includes device_code, user_code, sign_in_url, interval, expires_in. Present sign_in_url (and the user_code) to the user.

2. Poll for the token every interval seconds:

curl -s -X POST https://shop.app/agents/auth/token \
  --data-urlencode 'grant_type=urn:ietf:params:oauth:grant-type:device_code' \
  --data-urlencode "device_code=$DEVICE_CODE"

Handle errors: authorization_pending (keep polling), slow_down (add 5s to interval), expired_token / access_denied (restart flow). Success returns access_token + refresh_token.

3. Validate:

curl -s https://shop.app/agents/auth/userinfo \
  -H "Authorization: Bearer $ACCESS_TOKEN"

4. Refresh on 401:

curl -s -X POST https://shop.app/agents/auth/token \
  --data-urlencode 'grant_type=refresh_token' \
  --data-urlencode "refresh_token=$REFRESH_TOKEN"

If refresh fails, restart the device flow.

Orders

Scope: Shop.app aggregates orders from all stores (not just Shopify) using email receipts the user connected in the Shop app. This skill never touches the user's email directly.

Status progression: paid → fulfilled → in_transit → out_for_delivery → delivered Other: attempted_delivery, refunded, cancelled, buyer_action_required

Fetch pattern

curl -s 'https://shop.app/agents/orders?limit=50' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "x-device-id: $DEVICE_ID"

Parameters: limit (1–50, default 20), cursor (from previous response).

Key fields to extract:

• Order UUID — uuid: …
• Store — at …, Store domain: …, Store URL: …
• Price — line after Store URL
• Date — Ordered: …
• Status / Delivery — Status: …, Delivery: …
• Reorder eligible — Can reorder: yes
• Items — under — Items —, each with optional [product:ID] [variant:ID] and Img:
• Tracking — under — Tracking — (carrier, code, tracking URL, ETA)
• Tracker ID — tracker_id: …
• Return URL — Return URL: … (only if eligible)

Pagination: if the first line is cursor: <value>, pass it back as ?cursor=<value> for the next page. Keep going until no cursor: line appears.

Filtering: apply client-side after fetch (by Ordered: date, Delivery: status, etc.).

Errors: on 401 refresh and retry. On 429 wait 10s and retry.

Tracking detail

Tracking lives under each order's — Tracking — section:

delivered via UPS — 1Z999AA10123456784
Tracking URL: https://ups.com/track?num=…
ETA: Arrives Tuesday

Stale tracking warning: if Ordered: is months old but delivery is still in_transit, tell the user tracking may be stale.

Returns

Two sources:

1. Order-level return URL — look for Return URL: … in the order data.

2. Product-level return policy:

curl -s 'https://shop.app/agents/returns?product_id=29923377167' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "x-device-id: $DEVICE_ID"

Fields: Returnable (yes / no / unknown), Return window (days), Return policy URL, Shipping policy URL.

For full policy text, fetch the return policy URL with web_extract (or curl + strip tags) — it's HTML.

Reorder

1. Fetch orders with limit=50, find target by uuid: or store/item match.
2. Confirm Can reorder: yes — if absent, reorder may not work.
3. Extract [variant:ID] and item title from — Items —, and the store domain from Store domain: or Store URL:.
4. Build the checkout URL: https://{domain}/cart/{variantId}:{quantity}.

Example: at Allbirds + Store domain: allbirds.myshopify.com + [variant:789012] → https://allbirds.myshopify.com/cart/789012:1

Missing variant (e.g. Amazon orders, no `[variant:ID]`): fall back to a store search link: https://{domain}/search?q={title}.

Build a Checkout URL

Pattern: https://{store}/cart/{variant_id}:{qty},{variant_id}:{qty}?checkout[email]=…

The Checkout: URL from search results contains {id} as a placeholder — swap in the real variant_id.

• Default: link the product page so the user can browse.
• "Buy now": use the checkout URL with a specific variant.
• Multi-item, same store: one combined URL.
• Multi-store: separate checkout URLs per store — tell the user.
• Never claim the purchase is complete. The user pays on the store's site.

Virtual Try-On & Visualization

When image_generate is available, offer to visualize products on the user:

• Clothing / shoes / accessories → virtual try-on using the user's photo
• Furniture / decor → place in the user's room photo
• Art / prints → preview on the user's wall

The first time the user searches clothing, accessories, furniture, decor, or art, mention this once: "Want to see how any of these would look on you? Send me a photo and I'll mock it up."

Results are approximate (colors, proportions, fit) — for inspiration, not exact representation.

Store Policies

Fetch directly from the store domain:

https://{shop_domain}/policies/shipping-policy
https://{shop_domain}/policies/refund-policy

These return HTML — use web_extract (or curl + strip tags) before presenting.

When you have a product_id from an order's line items, prefer GET /agents/returns?product_id=… for return eligibility + policy links.

Being an A+ Shopping Assistant

Lead with products, not narration.

Search strategy:

1. Search broadly first — vary terms, mix synonyms + category + brand angles. Use filters (min_price, max_price, ships_to) when relevant.
2. Evaluate — aim for 8–10 results across price / brand / style. Up to 3 re-search rounds with different queries. No "page 2" — vary the query.
3. Organize — group into 2–4 themes (use case, price tier, style).
4. Present — 3–6 products per group with image, name + brand, price (local currency when possible, ranges when min ≠ max), rating + review count, a one-line differentiator from the actual product data, options summary ("6 colors, sizes S-XXL"), product-page link, and a Buy Now checkout link.
5. Recommend — call out 1–2 standouts with a specific reason ("4.8 / 5 across 2,000+ reviews").
6. Ask one focused follow-up that moves toward a decision.

Discovery (broad request): search immediately, don't front-load clarifying questions. Refinement ("under $50", "in blue"): acknowledge briefly, show matches, re-search if thin. Comparisons: lead with the key tradeoff, specs side-by-side, situational recommendation.

Weak results? Don't give up after one query. Try broader terms, drop adjectives, category-only queries, brand names, or split compound queries. Example: dimmable vintage bulbs e27 → vintage edison bulbs → e27 dimmable bulbs → filament bulbs.

Order lookup strategy:

1. Fetch 50 orders (limit=50) — use a high limit for lookups.
2. Scan for matches by store (at <store>) or item title in — Items —. Match loosely — "Yoto" matches "Yoto Ltd".
3. Act on the match: tracking, returns, or reorder.
4. No match? Paginate with cursor, or ask for more detail.