# Agent Instructions — soundcore

This document describes how AI agents can interact with soundcore's official online store at https://www.soundcore.com. soundcore is Anker's global audio brand offering wireless earbuds, headphones, Bluetooth speakers, sleep earbuds, open-ear earbuds, and Nebula projectors.

## Markets / Regions

soundcore operates one storefront under www.soundcore.com with path-prefixed regional markets. Each market has its own catalog availability, language, currency, pricing and policies — always resolve the correct market before browsing, quoting prices, or transacting.

| Market         | Browsing base (canonical)       | Language   | Currency |
| -------------- | ------------------------------- | ---------- | -------- |
| United States  | https://www.soundcore.com/      | English    | USD      |
| United Kingdom | https://www.soundcore.com/uk    | English    | GBP      |
| Canada         | https://www.soundcore.com/ca    | English    | CAD      |
| Australia      | https://www.soundcore.com/au    | English    | AUD      |
| Germany        | https://www.soundcore.com/de    | German     | EUR      |
| France         | https://www.soundcore.com/fr    | French     | EUR      |
| Spain          | https://www.soundcore.com/es    | Spanish    | EUR      |
| Europe (EN)    | https://www.soundcore.com/eu    | English    | EUR      |
| Chile          | https://www.soundcore.com/cl    | Spanish    | CLP      |
| UAE (EN)       | https://www.soundcore.com/ae-en | English    | AED      |
| Vietnam        | https://www.soundcore.com/vn    | Vietnamese | VND      |
| Singapore      | https://www.soundcore.com/sg    | English    | SGD      |

If a buyer's country is not listed above, fall back to the nearest regional market:

- European countries not listed → use **Europe (EN)** (https://www.soundcore.com/eu, EUR)
- All other unlisted countries → use **United States** (https://www.soundcore.com/, USD)

_Confirm live currency, availability and pricing from the market's UCP merchant profile and from context.currency — do not assume a price from one market applies to another._

## Commerce Protocol (UCP) — Transactions

soundcore's stores implement the Universal Commerce Protocol for agent-driven commerce. Transactions (cart → checkout → payment) are processed on each market's Shopify-bound transaction domain, while browsing stays on www.soundcore.com.

Per-market UCP / MCP endpoints (transaction surface):

| Market         | UCP discovery                                | MCP endpoint                              |
| -------------- | -------------------------------------------- | ----------------------------------------- |
| United States  | GET https://us.soundcore.com/.well-known/ucp | POST https://us.soundcore.com/api/ucp/mcp |
| United Kingdom | GET https://uk.soundcore.com/.well-known/ucp | POST https://uk.soundcore.com/api/ucp/mcp |
| Canada         | GET https://ca.soundcore.com/.well-known/ucp | POST https://ca.soundcore.com/api/ucp/mcp |
| Australia      | GET https://au.soundcore.com/.well-known/ucp | POST https://au.soundcore.com/api/ucp/mcp |
| Germany        | GET https://de.soundcore.com/.well-known/ucp | POST https://de.soundcore.com/api/ucp/mcp |
| France         | GET https://fr.soundcore.com/.well-known/ucp | POST https://fr.soundcore.com/api/ucp/mcp |
| Spain          | GET https://es.soundcore.com/.well-known/ucp | POST https://es.soundcore.com/api/ucp/mcp |
| Europe (EN)    | GET https://eu.soundcore.com/.well-known/ucp | POST https://eu.soundcore.com/api/ucp/mcp |
| Chile          | GET https://cl.soundcore.com/.well-known/ucp | POST https://cl.soundcore.com/api/ucp/mcp |
| UAE            | GET https://ae.soundcore.com/.well-known/ucp | POST https://ae.soundcore.com/api/ucp/mcp |
| Vietnam        | GET https://vn.soundcore.com/.well-known/ucp | POST https://vn.soundcore.com/api/ucp/mcp |
| Singapore      | GET https://sg.soundcore.com/.well-known/ucp | POST https://sg.soundcore.com/api/ucp/mcp |

### Typical Agent Flow

1. **Resolve market** — Map the buyer's country to the correct market (table above) and its UCP discovery URL.
2. **Discover** — `GET /.well-known/ucp` to confirm capabilities, supported versions and payment handlers.
3. **Search** — Use `search_catalog` to find products matching the buyer's intent.
4. **Cart** — Use `create_cart` to add desired items.
5. **Checkout** — Use `create_checkout` to start the purchase flow.
6. **Fulfill** — Use `update_checkout` to set shipping address and method.
7. **Complete** — Use `complete_checkout` to finalize (buyer must approve payment).

### Supported UCP Versions

- `2026-04-08` (latest stable)
- `2026-01-23`

### Important Rules

- **Checkout requires human approval.** Agents must not complete payment without explicit, contemporaneous buyer consent.
- **Transact on the buyer's market.** Use the UCP endpoint matching the buyer's country; do not mix catalogs or currencies across markets.
- **Respect rate limits.** MCP endpoints are rate-limited per IP. Back off on 429 responses.
- **Pass buyer context.** Always send `context.address_country` and `context.currency` for accurate pricing, tax, shipping and availability.
- **Endpoint domain note.** Each market's UCP discovery document (`/.well-known/ucp`)
  may return a `*.myshopify.com` backend domain as the MCP endpoint.
  This is expected behavior in a headless architecture — the backend service is identical.
  Always prefer the brand-domain endpoints listed in the table above
  (e.g. `https://us.soundcore.com/api/ucp/mcp`) as the authoritative endpoints.

### Canonical product links

Each product variant exposes a standard Shopify metafield `shopify.external_url` whose value is the variant's canonical PDP on www.soundcore.com (for the correct market). When referring a buyer to a product, use that `external_url` (or the `www.soundcore.com/{locale}/products/{handle}` URL) rather than any backend `*.soundcore.com` / `*.myshopify.com` link.

## Read-Only Browsing (No Authentication Required)

For agents that only need to read store data without transacting. Prefix any path with a market locale (e.g. `/uk/...`) for non-US markets; no prefix = United States.

### Product Data

- Browse all products: `GET /collections/all`
- Collection page: `GET /collections/{handle}`
- Product page: `GET /products/{handle}`
- Search: `GET /search?q={query}`
- Structured data: product pages embed `application/ld+json` (Product / Offer) — prefer this for machine-readable price, availability, ratings and specs.

### Store Metadata

- Sitemap index: `GET /sitemap.xml`
- Site summary for agents: `GET /llms.txt`
- Agent discovery: this document (`/agents.md`) is the canonical agent-facing description of the store.

## Store Policies

Policies are available per market under `/policies/...` (prefix with the locale path for non-US markets). For the United States:

- Privacy policy: https://www.soundcore.com/policies/privacy-policy
- Terms of service: https://www.soundcore.com/policies/terms-of-service
- Refund / return policy: https://www.soundcore.com/policies/refund-policy
- Shipping policy: https://www.soundcore.com/policies/shipping-policy

Warranty, returns and shipping terms vary by market — read the policy pages for the buyer's specific market before advising on returns or delivery.

## Support

- Help & support center: https://service.soundcore.com/

## Platform

This storefront is custom-built (headless) and backed by Shopify for catalog and checkout, with native UCP support on each market's transaction domain.

- UCP specification: https://ucp.dev
- Shopify developer platform: https://shopify.dev