# Agent Instructions — Santala

This document describes how AI agents can interact with Santala's online store at https://santala.pro.

**You need no account, no API key and no software to shop here.** Everything in the next
section works with plain HTTPS from whatever tool you already have — a browsing tool, a
fetch call, curl. If you can also run a shell there is a CLI, but it is an optimisation,
not a requirement; see "If you can run a shell" near the end.

## Buying from this store

Four steps. Every one of them is a single HTTPS request.

**1. Find the product.**

```
GET https://santala.pro/api/storefront/products?q={query}
```

Add `&tags=tag1,tag2` (AND logic), `&max_price_in_cents=5000`, `&collection_id={id}`,
`&page={n}&per_page=24`. Omit `q` to list the whole catalog. Every result carries a
`product_number` — that is the identifier the next steps take.

**2. Inspect it, if it has variants.** Skip this when `has_variants` is `false`.

```
GET https://santala.pro/api/storefront/products/{slug_or_product_number}
```

The `variants` array is what you need a value from. Use a variant's `sku` — or its `id`
when `sku` is `null`, which is common, because variant skus are optional in Maksutin.

**3. Build a cart.** Nothing is charged and nothing is committed; the cart expires on its
own in 24 hours, and you may build as many as you like.

```
POST https://santala.pro/api/storefront/cart
Content-Type: application/json

{"items": [
  {"product_number": "PROD-XXXX-YYYY-ZZZ", "quantity": 1},
  {"product_number": "PROD-AAAA-BBBB-CCC", "quantity": 1, "variant_id": 18}
]}
```

Each item needs `product_number` (always present) or `sku` (may be empty), plus `quantity`.
When the product reports `has_variants: true`, add `variant_sku` or `variant_id`.

**4. Hand `cart.checkout_url` to the buyer.** Present it as a link with the total. That is
where your work ends — the buyer opens it and authorizes payment in their own browser.

There is also a shareable link that does steps 3 and 4 in one GET, if building a POST body
is awkward for you:

```
https://santala.pro/cart/prefill?items=PROD-XXXX-YYYY-ZZZ:2,SKU-456:1:S-RED
```

Each item is `<identifier>:<quantity>[:<variant>]`, where `<variant>` is a variant `sku` or
a variant `id`. The link builds the cart and redirects the buyer to checkout.

## The full instruction set

The four steps above are all you need to buy from this store. If you shop across several
Maksutin stores, or you want the complete flow written out — how to pick a store, what to
show the buyer, how to handle every failure — read:

[https://maksutin.fi/SKILL.md](https://maksutin.fi/SKILL.md)

**That is a document, not software.** Fetch it and follow it; there is nothing to install and
nothing to authorize. It is the same contract this page describes, written once for every
Maksutin store instead of one.

## If a call fails

Every failure names its own recovery, so you never have to guess or give up. REST answers
`{"error": {"code": "...", "message": "..."}}`; MCP returns the same in the payload with an
extra `suggested_action`. Never retry an identical request that just failed — one of these is
the next move:

| Code | What to do |
|---|---|
| `product_not_found` | Search again and use a `product_number` from the results |
| `variant_required` | Fetch the product; send the variant's `sku` as `variant_sku`, or its `id` as `variant_id` |
| `variant_not_found` | Fetch the product to see the real variants; sku-less ones are addressed by `variant_id` |
| `out_of_stock` | Lower the quantity, pick another variant, or tell the buyer it is sold out |
| `missing_identifier` | Every item needs a `product_number` or a `sku` |
| `too_many_items` / `quantity_too_large` | Stay under 50 line items and 100 units per line |
| `cart_not_found` / `cart_expired` | Build the cart again; carts live 24 hours |
| `ai_shopping_disabled` | This shop switched agent shopping off. Send the buyer to the normal website |
| `shop_not_found` | Nothing resolves on that host. Re-check it with the buyer |

A product with `has_variants: true` **always** needs a variant. Variant skus are optional in
Maksutin, so `sku: null` is common — that variant is addressed by its `id`, and there is
always a way through.

## Rules

- **Checkout requires the human.** This store does not accept agent-completed payment. There
  is no delegated payment instrument and no `complete_checkout` call — building a cart is the
  last step you take. Hand the `checkout_url` to the buyer.
- **Never invent identifiers.** Use only `product_number`, `sku`, `variant_sku` and `variant_id`
  values that came back from this shop's own API.
- **Do not POST to `/checkout` or `/orders`.** Those belong to the buyer's browser session.
- **Prices are authoritative server-side.** Any price you send is ignored and recalculated from
  current product data.
- **Currency is EUR.** All amounts are integers in cents; divide by 100 for display.
- **Respect rate limits.** Back off on `429` responses.
- **Cart limits.** Max 50 line items per cart, max 100 units per line. Carts expire 24 hours after creation.

## Reading this store more cheaply

Every product page, content page and listing supports markdown content negotiation. Send
`Accept: text/markdown` or append `.md` to any URL. Bodies are typically ~99 % smaller than the
HTML version, and every response carries an `x-markdown-tokens` estimate. Prefer this over
parsing HTML whenever you only need to read.

- `curl -H "Accept: text/markdown" https://santala.pro/{product-slug}`
- `curl https://santala.pro/{product-slug}.md`
- `curl https://santala.pro/products.md`
- `curl https://santala.pro/collections/{id}.md`

Collections group the catalog the way the merchant thinks about it:

- `GET https://santala.pro/api/storefront/collections`
- `GET https://santala.pro/api/storefront/collections/{id}`

## If you speak MCP

`POST https://santala.pro/mcp` with `Content-Type: application/json` — Streamable HTTP, MCP 2025-03-26,
no authentication; the shop is resolved from the host you call. Send `tools/list` for the
schemas. The tools mirror the flow above: `storefront_search_products`,
`storefront_get_product`, `storefront_create_cart`, `storefront_get_cart`,
`storefront_list_collections`, `storefront_get_shipping_options`.

MCP tools never answer with HTTP 4xx. Failures come back as
`{"error": {"code", "message", "suggested_action"}}`, and successes carry a `next_step`.

## If you can run a shell

Optional, and only for agents that can install software. The CLI wraps the same endpoints in
one command each:

```bash
npm install --global @phenomenal-development/maksutin-cli
maksutin search "gift" --shop santala.pro
```

It can do nothing you cannot do with the four requests above, and it cannot pay either. If
you have no shell, you are not missing a capability — skip this section.

## Commerce protocols

This store publishes a [Universal Commerce Protocol](https://ucp.dev) profile at
`https://santala.pro/.well-known/ucp` (version `2026-04-08`) and an
Agentic Commerce Protocol discovery document at `https://santala.pro/.well-known/acp.json`. Both describe
the same surface this document does.

## Every discovery URL on this store

- Agent instructions: `https://santala.pro/agents.md` — this document, the canonical agent-facing description of the store
- LLM instructions: `GET https://santala.pro/llms.txt`
- Shopping manifest: `GET https://santala.pro/.well-known/ai-shopping.json`
- UCP profile: `GET https://santala.pro/.well-known/ucp`
- ACP discovery: `GET https://santala.pro/.well-known/acp.json`
- API catalog (RFC 9727): `GET https://santala.pro/.well-known/api-catalog`
- MCP server card: `GET https://santala.pro/.well-known/mcp/server-card.json`
- Agent skills index: `GET https://santala.pro/.well-known/agent-skills/index.json`
- Sitemap: `GET https://santala.pro/sitemap.xml`

## Store Policies
- **Tietosuojaseloste**: https://santala.pro/tietosuojaseloste
- **Toimitusehdot**: https://santala.pro/toimitusehdot

Full policies are available at the URLs above, and each one also serves markdown via `Accept: text/markdown`.

## Platform

This store is built on [Maksutin](https://maksutin.fi), a Finnish commerce platform. Every Maksutin
shop exposes the agent surface described above natively, so a client written against one shop
works against all of them.

- Start your own store: https://maksutin.fi
- Platform skill (recommended for personal shopping agents): https://maksutin.fi/SKILL.md
- CLI: https://www.npmjs.com/package/@phenomenal-development/maksutin-cli
- UCP specification: https://ucp.dev