# Tannico — Agent Instructions

> Italy's leading online wine shop since 2013. Over 12,000 labels from 2,500+ wineries across 23 countries. Part of CASTEL-Vins since 2025. This document explains how AI agents can discover, browse, and transact on Tannico's store.

Tannico ([tannico.it](https://www.tannico.it)) is an Italian wine e-commerce platform specialising in the curated sale of Italian and international wines, spirits, champagne, and specialty beverages. The store is built on Shopify.

Alcohol regulations apply — agents must confirm age eligibility before completing any purchase (18+ in Italy and most of Europe, 21+ in the US). Checkout requires explicit buyer consent; agents must not complete payment without it. Not all products can be shipped to all countries — wine shipments may be subject to customs duties, import limits, and local alcohol regulations. Always pass the buyer's country to get accurate availability. Free shipping on tannico.it for orders over €69. Prices are in EUR on tannico.it; other storefronts use local currencies (see Store Info below).

## Commerce Protocol (UCP)

- [UCP discovery endpoint](https://www.tannico.it/.well-known/ucp): Returns the merchant profile with supported UCP versions, MCP service endpoint, capabilities, and payment handlers. Agents must obtain the MCP endpoint URL from this response — do not hardcode it.
- [UCP specification](https://ucp.dev): The Universal Commerce Protocol standard for agent-driven commerce.

Supported UCP versions: `2026-04-08` (latest stable), `2026-01-23`.

Capabilities: `dev.ucp.shopping.checkout` (checkout session management), `dev.ucp.shopping.cart` (cart creation and updates), `dev.ucp.shopping.fulfillment` (shipping options — single-destination, shipping only), `dev.ucp.shopping.discount` (discount code application), `dev.ucp.shopping.order` (order lifecycle tracking), `dev.ucp.shopping.catalog.search` (product search), `dev.ucp.shopping.catalog.lookup` (product lookup by ID), `dev.shopify.catalog` (Shopify-enhanced catalog extending search and lookup).

Typical agent flow: (1) Discover — `GET /.well-known/ucp` to confirm capabilities. (2) Search — `search_catalog` to find products matching the buyer's intent. (3) Cart — `create_cart` to add items. (4) Checkout — `create_checkout` to start the purchase flow. (5) Fulfill — `update_checkout` to set shipping address and method. (6) Complete — `complete_checkout` to finalize (buyer must approve payment). Respect rate limits — back off on 429 responses from the MCP endpoint.

Payment methods: Google Pay (Visa, Mastercard, Amex, Discover), credit/debit cards via Shopify Payments (Visa, Mastercard, Amex, Discover, Diners Club), Shop Pay, PayPal, Klarna (buy now pay later).

## Catalog Structure

Product types on tannico.it use Italian-language values: `rosso` (red wine), `bianco` (white wine), `rosé`, `spumante` (sparkling wine), `champagne`, `orange wine`, `dolce (vino)` (sweet/dessert wine), `liquoroso` (fortified wine), `distillato` (spirit), `amaro e liquore` (bitters and liqueurs), `vermouth`, `sake`, `cocktail` (ready-to-drink), `No/low Alcol` (non-alcoholic), `bundle` (curated wine box), `gift card` (€25, €50, €75, €100, €250).

Collections follow predictable URL patterns at `/collections/{handle}` in Italian. Patterns by dimension: colour (`vini-rossi`, `vini-bianchi`, `vini-rosati`), denomination with colour prefix (`i-rossi-barolo`, `bianchi-soave`, `bollicine-franciacorta`), grape variety (`nebbiolo`, `sangiovese`, `vermentino`), region (`piemonte`, `toscana`, `sicilia`), winery slug (`antinori`, `gaja`, `produttori-del-barbaresco`), occasion (`vini-da-regalare`, `vini-estivi`), food pairing with `-abbinamenti` suffix (`barolo-abbinamenti`, `prosecco-abbinamenti`).

Each wine product includes: title with vintage and producer (e.g. `Barolo DOCG "Roncaglie" 2020 - Chionetti`), appellation (DOCG/DOC/IGT), grape varieties with percentages, alcohol content, bottle size (0.375L, 0.75L, 1.5L Magnum, 3L Jéroboam), serving temperature, drinking window, food pairings, and Tannico's sommelier rating out of 100.

Wine-specific data is stored in Shopify metafields under the `custom` namespace: `custom.grape_varieties` (grape varieties), `custom.appellations` (DOC/DOCG/IGT denomination), `custom.regions` (wine region), `custom.countries` (country of origin), `custom.vintage` (harvest year), `custom.bottle_size` (bottle format), `custom.typologies` (wine typology), `custom.pairings` (food pairings), `custom.tannico_rating` (sommelier score out of 100).

Search tips: by denomination (`Barolo`, `Brunello di Montalcino`, `Amarone`), by grape (`Nebbiolo`, `Sangiovese`, `Vermentino`), by producer (winery name, e.g. `Gaja`, `Antinori`), by occasion (`regalo`, `aperitivo`, `barbecue`), by pairing (`pesce`, `carne rossa`, `formaggi`), by style (`biologico`, `naturale`, `biodinamico`). Search queries in Italian yield the best results on tannico.it.

## Catalog

- [Red wines](https://www.tannico.it/collections/vini-rossi): Italian and international reds — Barolo, Brunello, Chianti, Amarone, Primitivo, Nero d'Avola
- [White wines](https://www.tannico.it/collections/vini-bianchi): Vermentino, Soave, Verdicchio, Friulano, Gewürztraminer, Sauvignon Blanc
- [Rosé wines](https://www.tannico.it/collections/vini-rosati): Italian rosato and international rosé
- [Sparkling wines](https://www.tannico.it/collections/bollicine): Prosecco, Franciacorta, Metodo Classico, Crémant, Cava
- [Champagne](https://www.tannico.it/collections/champagne): Grower and Maison Champagnes
- [Natural wines](https://www.tannico.it/collections/vini-naturali): Organic, biodynamic, and natural wines
- [Spirits](https://www.tannico.it/collections/spirits): Grappa, whisky, gin, rum, brandy
- [Amari and liqueurs](https://www.tannico.it/collections/amari-e-liquori): Italian bitters and liqueurs
- [Gift cards](https://www.tannico.it/collections/gift-card): €25, €50, €75, €100, €250
- [Tasting boxes](https://www.tannico.it/collections/box-di-vino-degustazione): Curated wine selections and gift sets
- [Awarded and top rated](https://www.tannico.it/collections/vini-rari-premiati): Rare and high-scoring wines

## Returns Policy

- [Terms and conditions](https://www.iubenda.com/termini-e-condizioni/848639): Right of withdrawal per Italian consumer law. Contact info@tannico.it for change-of-mind returns, damaged products (send a photo of the bottle), or defective products such as corked wine (keep the bottle for inspection).

## Read-Only Browsing

- [All products](https://www.tannico.it/collections/all): Browse the full catalog
- [Sitemap](https://www.tannico.it/sitemap.xml): Full sitemap index
- [Collection sitemap 1](https://www.tannico.it/sitemap_collections_1.xml?from=656586277204&to=672212812116): Collections batch 1
- [Collection sitemap 2](https://www.tannico.it/sitemap_collections_2.xml?from=672212844884&to=684801720660): Collections batch 2
- [Collection sitemap 3](https://www.tannico.it/sitemap_collections_3.xml?from=684801753428&to=712278016340): Collections batch 3
- [LLM context](https://www.tannico.it/llms.txt): Concise store overview for language models

Product JSON is available at `/products/{handle}.json`, collection products at `/collections/{handle}/products.json`, and search at `/search?q={query}&type=product`. No authentication required.

## Store Info

- [About Tannico](https://www.tannico.it/pages/about-us): Company history, mission, CASTEL-Vins ownership
- [Privacy policy](https://www.tannico.it/policies/privacy-policy): Data handling and privacy
- [Tannico Italy](https://www.tannico.it): Primary storefront (Italian, EUR)
- [Tannico France](https://www.tannico.fr): French storefront (EUR)
- [Tannico Spain](https://www.tannico.es): Spanish storefront (EUR)
- [Tannico Germany](https://de.tannico.com): German storefront (EUR)
- [Tannico International](https://www.tannico.com): English storefront (USD)
- [Tannico UK](https://www.tannico.co.uk): British storefront (GBP)
- [Tannico Sweden](https://se.tannico.com): Swedish storefront (SEK)
- Customer support: info@tannico.it / +39 02 9475 7947

## Optional

- [Barolo](https://www.tannico.it/collections/i-rossi-barolo): Piedmont's most prestigious DOCG red, 100% Nebbiolo
- [Barbaresco](https://www.tannico.it/collections/i-rossi-barbaresco): Elegant Nebbiolo-based DOCG from Langhe
- [Brunello di Montalcino](https://www.tannico.it/collections/i-rossi-brunello-di-montalcino): Tuscan DOCG, 100% Sangiovese Grosso
- [Chianti Classico](https://www.tannico.it/collections/i-rossi-chianti-classico): Historic Tuscan DOCG, Sangiovese-based
- [Amarone della Valpolicella](https://www.tannico.it/collections/i-rossi-amarone-della-valpolicella): Veneto DOCG from dried grapes
- [Bolgheri](https://www.tannico.it/collections/i-rossi-bolgheri): Tuscan coast DOC, Bordeaux-style blends
- [Franciacorta](https://www.tannico.it/collections/bollicine-franciacorta): Lombardy DOCG, traditional method sparkling
- [Prosecco](https://www.tannico.it/collections/bollicine-prosecco): Veneto/Friuli DOC, Glera-based sparkling
- [Soave](https://www.tannico.it/collections/bianchi-soave): Veneto DOC, Garganega-based white
- [Nebbiolo](https://www.tannico.it/collections/nebbiolo): Noble Piedmontese grape — Barolo, Barbaresco, Langhe, Roero
- [Sangiovese](https://www.tannico.it/collections/sangiovese): Tuscany's signature grape — Chianti, Brunello, Morellino
- [Vermentino](https://www.tannico.it/collections/vermentino): Mediterranean white — Sardegna, Liguria, Toscana
- [Primitivo](https://www.tannico.it/collections/primitivo): Puglia's warm-climate red grape
- [Nero d'Avola](https://www.tannico.it/collections/nero-d-avola): Sicily's flagship red grape
- [Pinot Nero](https://www.tannico.it/collections/pinot-nero): Italian Pinot Noir — Alto Adige, Oltrepò Pavese
- [Barolo abbinamenti](https://www.tannico.it/collections/barolo-abbinamenti): Barolo food pairing guide
- [Prosecco abbinamenti](https://www.tannico.it/collections/prosecco-abbinamenti): Prosecco food pairing guide
- [Vermentino abbinamenti](https://www.tannico.it/collections/vermentino-abbinamenti): Vermentino food pairing guide
- [Piemonte](https://www.tannico.it/collections/piemonte): Barolo, Barbaresco, Barbera, Moscato
- [Toscana](https://www.tannico.it/collections/toscana): Chianti, Brunello, Bolgheri, Vernaccia
- [Veneto](https://www.tannico.it/collections/veneto): Amarone, Prosecco, Soave, Valpolicella
- [Sicilia](https://www.tannico.it/collections/sicilia): Nero d'Avola, Etna, Grillo, Marsala
- [Puglia](https://www.tannico.it/collections/puglia): Primitivo, Negroamaro, Bombino
- [Campania](https://www.tannico.it/collections/campania): Aglianico, Fiano, Greco, Falanghina
- [Friuli Venezia Giulia](https://www.tannico.it/collections/friuli-venezia-giulia): Friulano, Ribolla Gialla, Pinot Grigio
- [Alto Adige](https://www.tannico.it/collections/alto-adige): Gewürztraminer, Lagrein, Pinot Nero
- [Sardegna](https://www.tannico.it/collections/sardegna): Cannonau, Vermentino, Carignano
- [Lombardia](https://www.tannico.it/collections/lombardia): Franciacorta, Oltrepò Pavese, Valtellina