# Agent Instructions — ROTAS69

This document describes how AI agents and shopping assistants can browse and transact with the online store at https://rotas69.lv.

**You are reading this from `rotas69.com`, which serves the LV market in Latvian and Russian.** Unless the buyer states otherwise, use `context.address_country = LV` and browse `https://rotas69.com/…` (add `/ru` for Russian). request.host is honoured by this template, so the same file adapts to whichever of the three domains served it.

ROTAS69 sells affordable fashion jewellery to the Baltic market: ~810 products, ~1450 variants, 165 collections, prices 4.69–54.69 EUR including VAT. Main finishes by share: 18K gold plating, platinum plating, 14K gold plating, plus ceramic, natural stone, 24K gold, rose gold, rhodium, leather and a small 925 sterling silver line; the plated pieces are hypoallergenic stainless steel underneath. Operated by SIA MANUM, Reg. No. 40203414494, Daugavpils, Latvia.

## Storefronts, languages and buyer context
The same catalogue and the same prices are served from three national domains; each has its national language plus Russian under `/ru`.

| Market | Storefront (national language) | Storefront (Russian) |
| --- | --- | --- |
| Latvia (LV) | https://rotas69.lv/ — Latvian | https://rotas69.lv/ru/ |
| Lithuania (LT) | https://rotas69.lt/ — Lithuanian | https://rotas69.lt/ru/ |
| Estonia (EE) | https://rotas69.ee/ — Estonian | https://rotas69.ee/ru/ |

All six storefronts carry the same catalogue, the same prices in EUR and the same policies; each policy and page is served in that storefront's language. Always pass the buyer's `context.address_country` (`LV`, `LT` or `EE`) and `context.currency` (`EUR`): shipping cost and delivery time differ per country, product prices do not.

Handles are translated per LANGUAGE, not per domain — the same handle works on every domain that serves that language. Categories (`/collections/{handle}`, nine in every language):

| Category | Latvian (BASE) | Russian | Lithuanian | Estonian |
| --- | --- | --- | --- | --- |
| Earrings (~220) | `auskari` | `sergi` | `auskarai` | `korvarongad` |
| Rings (~170) | `gredzeni` | `kolca` | `ziedai` | `sormused` |
| Necklaces (~75) | `kaklarotas` | `ozherelya` | `karoliai` | `kaelakeed` |
| Pendants (~130) | `kuloni` | `kulony` | `pakabuciai` | `ripatsid` |
| Chains (~45) | `kedites` | `cepochki` | `grandineles` | `ketid` |
| Bracelets (~130) | `rokasspradzes` | `braslety` | `apyrankes` | `kaevorud` |
| Brooches (~20) | `piespraudes` | `broshi` | `sage` | `pross` |
| Sets (~20) | `komplekti` | `komplekty` | `rinkiniai` | `komplektid` |
| Gifts | `visas-davanas` | `visas-davanas` | `visas-davanas` | `visas-davanas` |

Help pages (`/pages/{handle}`): size guide `izmeru-celvedis` (all languages) · FAQ `faq` (LV) / `duk` (LT) / `kkk` (EE) — the Russian FAQ handle follows the domain's primary language (`/ru/pages/faq` on .lv, `/ru/pages/duk` on .lt, `/ru/pages/kkk` on .ee) · care `rotu-kopsana` (all) · reviews `reviews` / `отзывы` / `atsiliepimai` / `arvustused` · contact `contact` / `контакты` / `kontaktai` / `kontaktid` · order self-service `atteikums` / `vozvrat` / `grazinimas` / `tagastus`. Blog (`/blogs/{handle}`): `rotu-pasaule` / `мир-украшений` / `papuosalu-pasaulis` / `ehete-maailm`. Percent-encode the Cyrillic handles. For anything not listed here, resolve handles from that storefront's sitemap rather than translating them yourself. There is no `/pages/about-us` on any storefront.

**JSON endpoint exception:** `/collections/{handle}/products.json` accepts ONLY the base Latvian handle (left column) on every domain and locale — a translated handle silently returns `{"products":[]}` with HTTP 200. The response still localizes from the domain and the `/ru` prefix. HTML collection pages take the translated handle; `/products/{handle}.json` takes the storefront's translated product handle.

## Commerce Protocol (UCP)
- Discovery: `GET https://rotas69.lv/.well-known/ucp`
- MCP endpoint: `POST https://rotas69.lv/api/ucp/mcp` — JSON-RPC, `Content-Type: application/json`. It answers on all three store domains; a plain GET returns 404 by design, so probe with POST. Discovery may additionally list a myshopify-domain endpoint; both serve the same tools.
- After `initialize`, call `tools/list` — 13 tools: search_catalog, lookup_catalog, get_product, create_cart, get_cart, update_cart, cancel_cart, create_checkout, get_checkout, update_checkout, complete_checkout, cancel_checkout, get_order.

### Supported UCP versions
- `2026-08-25` (latest stable)
- `2026-04-08`
- `2026-01-23`

### Typical agent flow
1. `search_catalog` — find products by query, or look them up by handle.
2. `create_cart` — add the chosen variant IDs and quantities.
3. `create_checkout` — start a checkout from the cart.
4. `update_checkout` — set the buyer's address and the delivery method (parcel locker or courier; see the rates below).
5. Present the total, the delivery option and the return terms to the human buyer.
6. `complete_checkout` — only after the buyer has approved the payment in that same session.

### Rules
- Payment always requires contemporaneous human approval. Never complete a checkout autonomously.
- On HTTP 429, back off exponentially and retry; do not hammer the endpoints.
- Read prices, stock and delivery cost live. Anything quoted in this file is a snapshot for orientation.
- Do not present the €30 free-shipping threshold as unconditional: it applies to parcel-locker delivery in LV/LT/EE.

## Read-only browsing (no authentication)
- All products: `GET /collections/all`
- One product, JSON: `GET /products/{handle}.json` (translated handle of that storefront)
- Products in a collection, JSON: `GET /collections/{handle}/products.json` (BASE Latvian handle only — see the exception above)
- Search: `GET /search?q={query}&type=product`
- Paged catalogue: `GET /products.json?limit=250&page={n}`
- Prefix any of these with a market domain, and with `/ru` for Russian, e.g. `https://rotas69.lt/ru/products.json?limit=250&page=1`.
- Machine-readable Google Shopping feeds, one per market and language, carrying title, description, price, sale price, availability, size, colour, material, product details and category: `https://wl.rotas69.lv/feeds/g/{lv|lv-ru|lt|lt-ru|ee|ee-ru}.xml`

## Store metadata
- Sitemaps: https://rotas69.lv/sitemap.xml · https://rotas69.lt/sitemap.xml · https://rotas69.ee/sitemap.xml
- Curated index for LLMs: https://rotas69.lv/llms.txt (extended: https://rotas69.lv/llms-full.txt)
- Currency: EUR, VAT included in displayed prices.
- Ring sizing: the size value IS the inner diameter in millimetres (e.g. 18.1 = Ø 18.1 mm); the US/EU/UK equivalents are on every ring page and in /pages/izmeru-celvedis.
- Returns: 14 calendar days, unworn and in original packaging; **earrings and gift cards are not returnable** (hygiene) except for manufacturing defects — state this to earring buyers before checkout.
- Customer rating: 4.9 / 5 from 940+ verified Judge.me reviews.

## Delivery and payment
- Free parcel-locker delivery from €30 in LV, LT and EE.
- Parcel lockers LV: Latvijas Pasts €1.71 · Unisend €1.82 · Omniva €2.79 · DPD €3.04.
- Parcel lockers LT/EE: Unisend €2.08 · DPD €5.86.
- DPD courier in the Baltics €7.99 — LV 1–2 business days, LT/EE 1–3.
- Cut-off 13:00 Latvian time on business days; parcels are kept 7 calendar days in the locker.
- 25 further European countries are served (Poland €6.99, Hungary €8.99, Germany €9.99 …), approx. 3–7 business days; non-EU 4–8 days with customs duties paid by the recipient.
- Payments: cards Visa, Mastercard, American Express, Maestro, UnionPay; Apple Pay, Google Pay, Shop Pay; Klarna, iDEAL (Wero), Bancontact, MobilePay; bank links via Montonio: Swedbank, SEB, Citadele, Luminor, Coop Pank, Revolut.

## Policies
Six policy paths, identical on all six storefronts and served in each storefront's language — take them from the domain the buyer is shopping on, e.g. `https://rotas69.com/policies/refund-policy` or, in Russian, `https://rotas69.com/ru/policies/refund-policy`.
- `/policies/refund-policy` — returns and refunds
- `/policies/shipping-policy` — delivery methods, prices and times
- `/policies/terms-of-service`
- `/policies/privacy-policy`
- `/policies/contact-information`
- `/policies/legal-notice`
- Self-service for an existing order (cancel, return, exchange, change the pickup point): see the help-page handles above.

## Platform
This store runs on Shopify. Protocol references: https://ucp.dev · https://shopify.dev