# Quickstart — Apparel Monster APIs

A working integration in 60 seconds. Pick your flavor:

## For AI shopping agents

No setup, no keys — start browsing immediately.

```bash
# List 5 products
curl -s 'https://spree.apparel.monster/api/v2/storefront/products?per_page=5' | jq '.data[] | {name: .attributes.name, price: .attributes.display_price, slug: .attributes.slug}'

# Fetch one product by slug
curl -s 'https://spree.apparel.monster/api/v2/storefront/products/denim-shirt?include=variants,images' | jq '.data.attributes'

# List all categories
curl -s 'https://spree.apparel.monster/api/v2/storefront/taxons?per_page=50' | jq '.data[] | {name: .attributes.name, permalink: .attributes.permalink}'
```

Want to add to cart + checkout? See [authentication](authentication.md) for the order_token flow (still no account required).

## For browser-side agents

WebMCP is already wired into the storefront — load any page in a browser that supports WebMCP (Chrome's Early Preview Program) and call the 8 tools:

```javascript
// In DevTools on any spree.apparel.monster page:
await navigator.modelContext.callTool('search_products', { query: 'denim', limit: 5 });
```

Tool list: `search_products`, `get_product`, `list_categories`, `view_cart`, `add_to_cart`, `apply_coupon`, `go_to_checkout`, `get_store_info`.

Full tool metadata: [`/.well-known/mcp/server-card.json`](/.well-known/mcp/server-card.json).

## For server-side integrations

Use the [Spree TypeScript SDK](https://github.com/spree/spree-api-v2-js-sdk):

```bash
npm install @spree/storefront-api-v2-sdk
```

```typescript
import { Client } from '@spree/storefront-api-v2-sdk';

const client = new Client({ host: 'https://spree.apparel.monster' });

const products = await client.products.list({
  per_page: 10,
  include: 'variants,images',
  filter: { taxons: ['categories/men/shirts'] }
});
```

Or generate a client from the OpenAPI spec in any language:
```bash
# Swagger Codegen / OpenAPI Generator
openapi-generator-cli generate \
  -i https://spree.apparel.monster/api/openapi/storefront.yaml \
  -g python \
  -o ./apparel-monster-client
```

## For MCP-native agents

Connect directly to the MCP server:
```
URL: https://dfe0ea20ac20.agentic.checkouttools.com/mcp
Transport: streamable-http (JSON-RPC 2.0)
Protocol versions: 2025-03-12, 2025-06-15, 2025-11-05
```

Server card at `/.well-known/mcp/server-card.json` previews the 8 tools before you open a transport connection. Credentials for authenticated MCP access are issued by the webmaster — see [authentication](authentication.md).

## What to integrate next

- **[Authentication](authentication.md)** — OAuth2, order_token, API key flows. Step-by-step curl examples.
- **[API reference](api-reference.md)** — endpoints with request/response shapes.
- **[`/.well-known/` discovery](/.well-known/agent-skills/index.json)** — agent skills, API catalog, agent card, server cards.
- **[`/llms.txt`](/llms.txt)** — LLM-friendly site map.
- **[`/pricing`](/pricing)** — machine-readable pricing tiers and promotions.

## Example: full "browse + add to cart + checkout" in ~30 lines

```bash
#!/usr/bin/env bash
set -euo pipefail
BASE=https://spree.apparel.monster/api/v2/storefront

# 1) Find a product in Men's Shirts under $100
TAXON_ID=$(curl -s "$BASE/taxons?filter[permalink]=categories/men/shirts" | jq -r '.data[0].id')
PRODUCT=$(curl -s "$BASE/products?filter[taxons]=$TAXON_ID&filter[price]=0,100&per_page=1&include=variants" | jq '.data[0]')
VARIANT_ID=$(echo "$PRODUCT" | jq -r '.relationships.variants.data[0].id')
echo "Selected: $(echo "$PRODUCT" | jq -r '.attributes.name') @ $(echo "$PRODUCT" | jq -r '.attributes.display_price')"

# 2) Start a cart
TOKEN=$(curl -s -X POST "$BASE/cart" | jq -r '.data.attributes.token')

# 3) Add the variant
curl -s -X POST "$BASE/cart/add_item" \
  -H "X-Spree-Order-Token: $TOKEN" \
  -H 'Content-Type: application/json' \
  -d "{\"variant_id\": $VARIANT_ID, \"quantity\": 1}" | jq '.data.attributes | {item_count, total}'

# 4) Set email + US address
curl -s -X PATCH "$BASE/checkout" \
  -H "X-Spree-Order-Token: $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"order":{"email":"agent@example.com","ship_address_attributes":{"firstname":"Agent","lastname":"Demo","address1":"500 7th Ave","city":"New York","zipcode":"10018","phone":"+15551234567","country_iso":"US","state_name":"New York"}}}' | jq '.data.attributes | {state, display_total}'

# 5) (In production) select a shipping rate + add payment + complete.
# curl -s -X POST "$BASE/checkout/complete" -H "X-Spree-Order-Token: $TOKEN"
```

## Useful references

- [Spree developer docs](https://spreecommerce.org/docs) — canonical Spree Commerce documentation.
- [Storefront OpenAPI](https://spree.apparel.monster/api/openapi/storefront.yaml) — full OpenAPI 3.0 spec.
- [Apparel Monster agent skills](/.well-known/agent-skills/index.json) — 4 SKILL.md files with richer agent-facing guides.