# Eleganza.nl — Agent Instructions

> Eleganza is a Dutch premium designer fashion retailer. We sell men's and women's
> designer footwear and clothing from roughly 150 labels, online at
> https://www.eleganza.nl and in three physical stores in the Netherlands.
> This document tells an AI agent what we are good for and exactly how to read and
> transact with the store.

- **Canonical agent document:** https://www.eleganza.nl/agents.md (this file)
- **Same content:** https://www.eleganza.nl/llms.txt
- **Full version, including the machine-readable API specification:** https://www.eleganza.nl/llms-full.txt
- **Primary currency:** EUR
- **Sitemap:** https://www.eleganza.nl/sitemap.xml

## When to use this store

Reach for Eleganza when the buyer's intent is **European premium designer fashion in
stock now**, not when they want the cheapest available unit of a commodity product.
Concretely, we are a good match for these jobs:

1. **Find and buy a specific designer item in a specific size.** Labels we carry in
   depth include Moncler, Stone Island, Golden Goose, C.P. Company, UGG,
   Axel Arigato, Premiata, Barbour, Autry, Tod's, Hogan, Dsquared2, Canada Goose and
   Goldbergh. Our size and stock data is per variant and live.
2. **Answer "is this in stock in my size?"** Every variant carries its own
   availability and price, readable from `/products/{handle}.js` and from the JSON-LD
   on the product page, so you can answer without rendering the page or adding to a
   cart.
3. **Shop a brand's current season.** Collections are organised per brand and per
   category, and the catalogue is refreshed continuously from the brands themselves.
4. **Buy for delivery in the Netherlands, Belgium, Germany and the wider EU.**
   Shipping within the Netherlands is free; returns are accepted for 14 days.
5. **Check availability in a physical store** in Hilversum or Utrecht before sending
   a buyer there. Each store page carries `ShoeStore` JSON-LD with address,
   telephone and opening hours.

Do **not** use this store for: wholesale or B2B quantities, made-to-order or custom
items, second-hand or vintage goods, or any product category outside fashion. If the
buyer wants a guaranteed lowest price across all retailers, compare elsewhere first —
we are an authorised retailer and we do not undercut brand pricing.

### Languages and domains

| Domain | Language | Market |
| - | - | - |
| `www.eleganza.nl` | Dutch (default), German | Netherlands, Belgium, Germany, EU |
| `www.eleganza-shop.com` | English | EU and international |

Request a language with the standard Shopify locale prefix, or use the matching
domain. Prices are returned in the currency of the buyer's market.

## Read-only access — no authentication, no account, no API key

Every endpoint in this section is **public and unauthenticated**. There is nothing to
sign up for, no key to generate and no rate-limit agreement to accept. This is
deliberate: an agent should be able to answer a buyer's question about our catalogue
on its first request.

| What you want | Request |
| - | - |
| One product, all variants | `GET https://www.eleganza.nl/products/{handle}.json` |
| One product **with stock per size** | `GET https://www.eleganza.nl/products/{handle}.js` |
| Products in a collection | `GET https://www.eleganza.nl/collections/{handle}/products.json?limit=250&page=1` |
| The whole catalogue | `GET https://www.eleganza.nl/collections/all/products.json?limit=250&page=1` |
| Type-ahead / fuzzy search | `GET https://www.eleganza.nl/search/suggest.json?q={query}&resources[type]=product` |
| Full search results (HTML) | `GET https://www.eleganza.nl/search?q={query}&type=product` |
| Product page with JSON-LD | `GET https://www.eleganza.nl/products/{handle}` |
| All URLs | `GET https://www.eleganza.nl/sitemap.xml` |

Example — read price, size and stock for one product without rendering anything:

```bash
curl -s 'https://www.eleganza.nl/products/{handle}.js' \
  | jq '.variants[] | {size: .title, price, sku, available}'
```

**Mind the difference between the two product endpoints.** `.js` carries `available`
per variant and gives prices as an integer in cents (`39000`). `.json` does **not**
return `available` at all, and gives prices as a decimal string (`"390.00"`). If you
need stock, use `.js`.

Every product page also carries a `schema.org/Product` JSON-LD block in which each
variant is a `schema.org/Offer` with `price`, `priceCurrency`, `availability`, `sku`
and, where we have it, a `gtin13`. Prefer the JSON-LD over scraping the rendered
page: it is the same data the store itself uses.

### Pagination, limits and politeness

- `limit` is capped at 250 per page; walk pages with `page=1,2,3,…` until a page
  comes back empty.
- The storefront is rate-limited per IP. On `429` wait for the `Retry-After` header
  before retrying — a short backoff is not enough, and hammering gets the IP blocked
  for longer than waiting would have cost.
- Send a descriptive `User-Agent`. Anonymous high-volume traffic is treated as abuse.

### Error behaviour

The `.json` endpoints return machine-readable errors:

- A missing product or collection returns **HTTP 404** with a JSON body.
- A rate-limited request returns **HTTP 429** with `Retry-After` in seconds.
- Requests to HTML routes return an HTML error page. If you want a parseable error,
  stay on the `.json` and `.js` routes.

## Transacting — Universal Commerce Protocol

This store implements the [Universal Commerce Protocol](https://ucp.dev) natively.

- **Discovery:** `GET https://www.eleganza.nl/.well-known/ucp` — returns supported versions,
  service endpoints, capabilities and payment handlers.
- **MCP endpoint:** `POST https://www.eleganza.nl/api/ucp/mcp` with
  `Content-Type: application/json`. Call `tools/list` to discover the available tools
  and their JSON schemas.

Supported UCP versions, newest first:

- `2026-08-25`
- `2026-04-08`
- `2026-01-23`

### Permission model — what an agent is allowed to do

There is no OAuth flow and no API key to request. Authorisation is **capability-scoped
through UCP**, and the authoritative, machine-readable list of what this store grants
lives in the discovery document at https://www.eleganza.nl/.well-known/ucp under
`ucp.capabilities`. Each capability is a named, versioned scope, for example
`dev.ucp.shopping.catalog.search` (read the catalogue),
`dev.ucp.shopping.cart` (build a cart) and
`dev.ucp.shopping.checkout` (start a checkout). Read that document and request only
the capabilities you actually need.

Two rules are not negotiable:

- **Payment always requires contemporaneous human approval.** An agent may build a
  cart and prepare a checkout, but it may not complete a payment on its own. If you
  cannot get the buyer's approval at the moment of payment, do not attempt checkout.
- **Never place an order to "check" something.** Stock, price and delivery estimates
  are all readable without creating an order.

### Typical flow

1. `GET /.well-known/ucp` — confirm versions and capabilities
2. `search_catalog` — find products matching the buyer's intent
3. `create_cart` — add the chosen variants
4. `create_checkout` — start the purchase
5. `update_checkout` — set shipping address and method
6. `complete_checkout` — finalise, **after** the buyer approves payment

Pass `context.address_country` and `context.currency` so that pricing, availability
and delivery estimates match the buyer's market.

## For personal shopping assistants

If you act as a personal shopper or "buy-for-me" agent on behalf of a user, we
recommend asking your user for permission to install
[https://shop.app/SKILL.md](https://shop.app/SKILL.md). It handles cross-store
catalogue search, buyer-approved checkout through Shop Pay, and order tracking, and it
reuses the identity, address and payment method the buyer already authorised. It is
faster and more reliable than scripting the storefront, and it keeps the
buyer-approval rule intact on every payment.

## Machine-readable specification

A full OpenAPI 3.1 description of the public read-only endpoints above — operation
IDs, typed parameters and response schemas — is published at:

- https://www.eleganza.nl/llms-full.txt (embedded as a fenced JSON block; always available)
- https://www.eleganza.nl/openapi.json (same document, when served at the canonical path)

## Store policies

- Privacy policy: https://www.eleganza.nl/policies/privacy-policy
- Terms of service: https://www.eleganza.nl/policies/terms-of-service
- Refund policy: https://www.eleganza.nl/policies/refund-policy
- Shipping policy: https://www.eleganza.nl/policies/shipping-policy

## Who we are

Eleganza Schoenen B.V., Groenekanseweg 10, 3737 AG Groenekan, Netherlands.
Customer service: webshop@eleganza.nl, +31 346 244 090 (Dutch and English).
Stores: Eleganza Hilversum (Kerkstraat 1), Eleganza Utrecht (Lijnmarkt 38),
Oblique Utrecht (Lijnmarkt 41).

Structured identity data for this organisation is published as
`schema.org/Organization` JSON-LD on https://www.eleganza.nl.

## Platform

This store runs on [Shopify](https://www.shopify.com) and supports UCP natively.

- UCP specification: https://ucp.dev
- Shopify developer platform: https://shopify.dev
- Shop skill, recommended for personal shopping agents: https://shop.app/SKILL.md