# 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.lv`, which serves the LV market in Latvian and Russian.** Unless the buyer states otherwise, use `context.address_country = LV` and browse `https://rotas69.lv/…` (add `/ru` for Russian). request.host is honoured by this template, so the same file adapts to whichever of the four domains served it.

ROTAS69 sells affordable fashion jewellery to the Baltic market and, on rotas69.com, to 25 more European countries: ~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 with its national language plus Russian under `/ru`, and from rotas69.com in English for 25 more European countries.

| 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.com/.well-known/ucp`
- MCP endpoint: `POST https://rotas69.com/api/ucp/mcp` — JSON-RPC, `Content-Type: application/json`. It answers on all four 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|com}.xml`

## Store metadata
- Sitemaps: https://rotas69.com/sitemap.xml · https://rotas69.lt/sitemap.xml · https://rotas69.ee/sitemap.xml · https://rotas69.com/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 and LT 1–2 business days, 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 through rotas69.com (Poland €6.99, Hungary €8.99, Germany €9.99 …); DPD courier times in business days: Finland and Poland 2–4; Sweden 2–5; Austria, Belgium, Hungary, Luxembourg and the Netherlands 3–4; Czechia, Germany and Slovakia 3–5; Norway and Slovenia 3–6; Denmark and Switzerland 4–5; France, Romania and the United Kingdom 4–7; Italy 4–8; Bulgaria and Ireland 5–6; Portugal 5–7; Croatia and Spain 5–8; Greece 6–8. Outside the EU (UK, Switzerland, Norway) customs duties are 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.lv/policies/refund-policy` or, in Russian, `https://rotas69.lv/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