# aly.store API

> AI-native commerce platform for humans, developers, and agents.

## Storefront API (REST)
Base URL: https://aly.store/api/storefront/v1

### Catalog (public, no auth)
GET /stores/{slug} — Store info
GET /stores/{slug}/products — List products (paginated, filterable)
GET /stores/{slug}/products/{id} — Product detail
GET /stores/{slug}/collections — List collections
GET /stores/{slug}/collections/{slug_or_id} — Collection detail
GET /stores/{slug}/collections/{slug_or_id}/products — Collection products
GET /stores/{slug}/search?q={query} — Search with facets
POST /stores/{slug}/coupons/validate — Validate coupon code

### Cart (token-based)
POST /carts — Create cart (returns token)
GET /carts/{token} — Get cart
POST /carts/{token}/items — Add item
PATCH /carts/{token}/items/{id} — Update quantity
DELETE /carts/{token}/items/{id} — Remove item
POST /carts/{token}/coupon — Apply coupon
DELETE /carts/{token}/coupon — Remove coupon
POST /carts/{token}/checkout — Start checkout

### Orders (public, confirmation token)
GET /orders/{token} — Order status
GET /orders/{token}/downloads — Digital downloads

### Cross-store search
GET /search?q={query} — Search all stores

### Merchant management (validated API key: aly_*)
GET /merchant/orders?site_id={id} — List orders for a site
PATCH /merchant/orders/{id}/status — Update order status
POST /merchant/orders/{id}/fulfillments — Create fulfillment
GET /merchant/analytics?site_id={id} — Revenue & conversion analytics
GET /merchant/analytics/activity?site_id={id} — Activity feed
POST /merchant/products — Create product
PATCH /merchant/products/{id} — Update product
DELETE /merchant/products/{id} — Delete product
POST /merchant/webhooks — Register webhook
GET /merchant/webhooks?site_id={id} — List webhooks
PATCH /merchant/webhooks/{id} — Update webhook
DELETE /merchant/webhooks/{id} — Delete webhook

## AI Protocols
- UCP: https://aly.store/.well-known/ucp
- A2A: https://aly.store/.well-known/agent-card.json
- Protocol discovery: https://aly.store/.well-known/protocols
- MCP: https://aly.store/api/mcp (agent tools)
- OAuth 2.1: https://aly.store/.well-known/oauth-authorization-server

## Per-store discovery
Every published store also exposes its own root-level discovery surface at
`https://<slug>.aly.store/` — visit `/.well-known/ucp`, `/.well-known/agent-card.json`,
`/llms.txt`, `/sitemap.xml`, or `/feed/google-merchant.xml` on that host
for store-specific manifests.