# Agent Instructions — Coffee Circle This document describes how AI agents can interact with Coffee Circle's online store at https://www.coffeecircle.com. ## This is Coffee Circle At Coffee Circle, we offer the world’s finest coffee and equipment. We roast all coffees to perfection and serve and ship them freshly. We always aim to deliver the best flavor experience for our customers. We stand for respect and true fairness in the value chain. We source directly from coffee growers and pay high prices for high-quality coffee. We treat people how we want to be treated, and respect all humans as they are. We maintain open, honest, and transparent communication with our partners. In all we do, we uphold the highest moral standards to sustain the planet and humanity. We drive sustainable change in the growing regions and support research on the climate resilience of coffee in order to secure the income of coffee farmers and their families in future generations. With your purchase you support us. You can find more information on our [social projects page](https://www.coffeecircle.com/en/e/foundation). ## For Personal Shopping Assistants and Agents Acting On Behalf of a User There is **no self-hosted agent-commerce API** on this storefront (no UCP/MCP endpoint). The read-only browsing routes below let you discover products and build a cart; the actual payment step always happens on Shopify's hosted checkout and always requires explicit buyer approval. ## URL Structure All content pages are **locale-prefixed**. Supported locales: - `de` — German (default; also served at the bare domain root) - `en` — English Replace `{lang}` with `de` or `en` and `{handle}` with the page's handle in the patterns below. ### Read-Only Browsing (No Authentication Required) | Purpose | URL pattern | | ---------------------------------------- | -------------------------- | | Homepage | `GET /{lang}` | | Coffee product | `GET /{lang}/k/{handle}` | | Equipment / other product | `GET /{lang}/p/{handle}` | | Collection | `GET /{lang}/c/{handle}` | | Equipment collection | `GET /{lang}/g/{handle}` | | Content & landing pages (incl. policies) | `GET /{lang}/e/{handle}` | | Blog index | `GET /{lang}/a` | | Blog category | `GET /{lang}/a/{category}` | | Blog post | `GET /{lang}/b/{handle}` | Examples: - Coffee: `https://www.coffeecircle.com/de/k/yirgacheffe` - Equipment: `https://www.coffeecircle.com/de/p/chemex-kaffeekaraffe` - Collection: `https://www.coffeecircle.com/en/c/filter-coffee-shop` Notes: - There are **no Shopify Liquid endpoints** on this domain — `/products/{handle}`, `/collections/{handle}`, `/policies/*`, and the `.json` variants (`/products/{handle}.json`, `/collections/{handle}/products.json`) do **not** exist here. - On-site search is a client-side (Algolia) overlay with **no crawlable `?q=` URL**. To enumerate the catalog, use the sitemap (below) rather than a search URL. ## Important Pages - **All Coffees and Espressos** (ground and whole bean, including decaffeinated coffees): https://www.coffeecircle.com/de/c/kaffee-shop - **Coffee Capsules** (Nespresso®-compatible capsules): https://www.coffeecircle.com/de/c/kaffeekapseln - **Coffee Equipment** (use #collection-links to dive deeper): https://www.coffeecircle.com/de/c/kaffeekapseln - **Subscription** (information on product subscriptions): https://www.coffeecircle.com/de/e/abo - **About Us** (what's special about Coffee Circle): https://www.coffeecircle.com/de/e/ueber-uns - **FAQ** (customer support portal): https://faq.coffeecircle.com/de ### Reading product data On collection pages, look for each `script` tag with type `ld+json` that contains `"@context":"http://schema.org","@type":"Product"` to receive first information about the offered products and the product's variants in structured form, including direct links and the sku to help you build a cart. On product pages, look for the `script` tag with type `ld+json` that contains `"@context":"http://schema.org","@type":"ProductGroup"` to receive additional information about the offered product and the product's variants in structured form, including direct links and the sku to help you build a cart. ### Cart and Checkout - **Add to cart via URL** — `GET /{lang}/checkout/add-via-url?skus={sku}:{qty},{sku}:{qty}&discount={code}` Adds one or more items (by Coffee Circle SKU) to the buyer's cart, optionally applies a discount code, then redirects to the cart page. Quantity defaults to `1` if omitted. Example: `https://www.coffeecircle.com/de/checkout/add-via-url?skus=K001-0250-001:2,Z002-001-001&discount=WELCOME` - **Cart page** — `GET /{lang}/checkout/cart` - **Checkout** — from the cart, the buyer is handed off to **Shopify's hosted checkout** by clicking the primary action "Zur Kasse" (or "Proceed to Checkout" in English). **Agents must not complete payment without explicit buyer consent.** ### Store Metadata - Sitemap: `GET /sitemap.xml` — direct (non-nested) list of all product, collection, content, and blog URLs for every locale. - Agent discovery: this document (`/agents.md`) is the canonical agent-facing description of the store. ## Store Policies Policy pages are content pages under `/{lang}/e/...`. German pages: - **Datenschutzerklärung** (privacy policy): https://www.coffeecircle.com/de/e/datenschutz - **AGB** (terms & conditions): https://www.coffeecircle.com/de/e/agb - **Versand** (shipping & delivery): https://www.coffeecircle.com/de/e/versand - **Retoure / Widerruf** (returns & right of withdrawal): https://www.coffeecircle.com/de/e/retoure - **Impressum** (legal notice): https://www.coffeecircle.com/de/e/impressum English versions exist under `/en/e/...` but use different paths (e.g. `/en/e/privacy`). Use `` hreflang links to resolve the exact English URLs.