API and Agent Documentation

This page describes how automated clients - AI shopping assistants, price monitors, integration scripts - should read and transact with the Keg Smiths storefront. Everything here is public and read-only unless stated otherwise.

Start here

Discovery: GET /.well-known/ucp returns this store's Universal Commerce Protocol merchant profile - supported protocol versions, service endpoints, capabilities and payment handlers.
Instructions: /llms.txt is the plain-language brief for assistants, including the rules around payment.
Tools: POST /api/ucp/mcp is a JSON-RPC 2.0 MCP endpoint. Call tools/list to get the authoritative input schema for every tool, then tools/call to use one.

MCP tools

Tool	Purpose
`search_catalog`	Find products matching a buyer's intent.
`lookup_catalog`	Resolve known identifiers to catalogue entries.
`get_product`	Fetch one product with variants and pricing.
`create_cart`, `get_cart`, `update_cart`, `cancel_cart`	Build and manage a cart.
`create_checkout`, `get_checkout`, `update_checkout`, `cancel_checkout`	Drive a checkout.
`complete_checkout`	Complete payment. Requires buyer approval - see below.
`get_order`	Retrieve an order the agent created.

Prices are integer minor units paired with an ISO 4217 currency code. {"amount": 2500, "currency": "USD"} is $25.00 - divide by 100 before quoting a price to a buyer. Pass context.address_country and context.currency for accurate pricing and availability.

Read-only JSON

If all you need is catalogue data, these need no credentials and no protocol:

GET /products/{handle}.json - one product with variants, pricing and images
GET /collections/{handle}.json - one collection
GET /collections/{handle}/products.json - the products in a collection
GET /search/suggest.json?q=QUERY - predictive search across products, collections and articles
GET /sitemap.xml - every indexable URL on this domain

Scoped permissions

Anything beyond the public catalogue goes through the Shopify Storefront GraphQL API at POST /api/2025-10/graphql.json and requires an access token in the X-Shopify-Storefront-Access-Token header.

Tokens are scoped. Each one is issued with an explicit list of permissions and can do nothing outside them, so an integration can be given exactly the access its job needs and no more:

unauthenticated_read_product_listings - published products, variants, prices, collections
unauthenticated_read_product_inventory - stock levels and availability
unauthenticated_read_product_tags - product tags used for filtering
unauthenticated_read_content - blog articles, pages and policies
unauthenticated_read_selling_plans - subscription and selling-plan options
unauthenticated_read_checkouts / unauthenticated_write_checkouts - read and modify a checkout the integration created; never completes payment
unauthenticated_read_customers / unauthenticated_write_customers - the signed-in customer, after customer authentication

A request with no token is rejected with unauthorized. A token that lacks the scope an operation needs is rejected with insufficient_scope, and the WWW-Authenticate header names the missing scope. To request a token, contact us with the integration name and the scopes it needs.

Errors

Machine-facing failures answer with the same JSON envelope. Branch on code: it is stable and never localised. resolution tells you what to do next.

{
  "error": {
    "code": "resource_not_found",
    "message": "No resource exists at /products/foo.json on this store.",
    "status": 404,
    "resolution": "Confirm the handle against https://www.kegsmiths.com/sitemap.xml, or call the search_catalog tool on POST /api/ucp/mcp to find the correct product.",
    "documentation_url": "https://www.kegsmiths.com/pages/api",
    "request_id": "01JD8K3M2QW9XA7YV4ZB6N0PCT"
  }
}

The codes are resource_not_found, route_not_found, method_not_allowed, invalid_request, unauthorized, insufficient_scope, rate_limited and upstream_error. The MCP endpoint reports tool-level failures inside the JSON-RPC error member instead, per the JSON-RPC 2.0 specification.

Rules for agents

Payment needs a human. Never complete a payment without contemporaneous buyer approval. If you cannot get approval at the moment of payment, route the purchase through Shop Pay instead - see /llms.txt.
Respect rate limits. The MCP endpoint is rate limited per IP. Back off when you receive a 429 and honour the Retry-After header.
Identify yourself. Send a descriptive User-Agent with a contact URL.
Prefer the API to scraping. The JSON endpoints above are faster, more stable and kinder to our origin than parsing HTML.

Questions

Integration questions, token requests and bulk or wholesale enquiries go to our contact page.