# API Reference — Apparel Monster Structured reference for the three Apparel Monster API surfaces. Prose-level introduction per surface, then links to the canonical OpenAPI specs. ## Surfaces | API | Base URL | Auth | OpenAPI spec | |---|---|---|---| | **Storefront API v2** | `/api/v2/storefront/` | none (reads), order_token (cart), Bearer (customer) | [`/api/openapi/storefront.yaml`](/api/openapi/storefront.yaml) | | **Platform API v2** | `/api/v2/platform/` | OAuth2 Bearer (admin scope) | [`/api/openapi/platform.yaml`](/api/openapi/platform.yaml) | | **OAuth 2.0** | `/spree_oauth/` | — | [`/api/openapi/oauth.yml`](/api/openapi/oauth.yml) | All specs are **OpenAPI 3.0**, mirrored daily from the upstream Spree Commerce repo. ## Storefront API — the 80% API This is the surface most AI shopping agents need. Everything is JSON:API-formatted (`{data: {id, type, attributes, relationships}}`). Unauthenticated reads cover the entire catalog. Cart and checkout use an `order_token` (no account required) or an OAuth2 Bearer token (customer account). ### Products ``` GET /api/v2/storefront/products GET /api/v2/storefront/products/{slug} ``` Filters: `filter[name]`, `filter[taxons]=`, `filter[price]=MIN,MAX`, `filter[options][]`, `filter[properties][]`, `filter[in_stock]=true`. Sort: `name`, `-name`, `price`, `-price`, `available_on`, `-available_on`, `popularity`, `-popularity`. Include (sideloads): `variants`, `images`, `taxons`, `option_types`, `product_properties`. Pagination: `page`, `per_page` (max 100). **Example — find women's dresses under $100:** ```bash TAXON=$(curl -s 'https://spree.apparel.monster/api/v2/storefront/taxons?filter[permalink]=categories/women/dresses' | jq -r '.data[0].id') curl -s "https://spree.apparel.monster/api/v2/storefront/products?filter[taxons]=$TAXON&filter[price]=0,100&per_page=10&include=variants" ``` ### Taxons (categories) ``` GET /api/v2/storefront/taxons GET /api/v2/storefront/taxons?filter[permalink]=categories/men GET /api/v2/storefront/taxons?filter[parent_permalink]=categories ``` ### Cart ``` POST /api/v2/storefront/cart # Create GET /api/v2/storefront/cart?include=line_items # Retrieve POST /api/v2/storefront/cart/add_item # Add variant PATCH /api/v2/storefront/cart/set_quantity # Update line quantity DELETE /api/v2/storefront/cart/remove_line_item/{id} # Remove PATCH /api/v2/storefront/cart/apply_coupon_code # Apply promo DELETE /api/v2/storefront/cart/remove_coupon_code/{code} # Remove promo POST /api/v2/storefront/cart/change_currency # (if multi-currency) POST /api/v2/storefront/cart/empty # Clear all items ``` Pass `X-Spree-Order-Token: ` on every cart call (after creating the cart). ### Checkout ``` PATCH /api/v2/storefront/checkout # Set email, addresses, next state PATCH /api/v2/storefront/checkout/select_shipping_method POST /api/v2/storefront/checkout/payments # Add payment POST /api/v2/storefront/checkout/complete # Place order GET /api/v2/storefront/checkout/payment_methods GET /api/v2/storefront/checkout/shipping_rates ``` ### Orders ``` GET /api/v2/storefront/order_status/{order_number}?order_token= GET /api/v2/storefront/account/orders # Authenticated ``` ### Account (authenticated) ``` GET /api/v2/storefront/account PATCH /api/v2/storefront/account GET /api/v2/storefront/account/addresses POST /api/v2/storefront/account/addresses PATCH /api/v2/storefront/account/addresses/{id} DELETE /api/v2/storefront/account/addresses/{id} GET /api/v2/storefront/account/credit_cards ``` ### Wishlist ``` GET /api/v2/storefront/wishlist POST /api/v2/storefront/wishlist/wished_items DELETE /api/v2/storefront/wishlist/wished_items/{id} ``` ### Full spec Full machine-readable spec: [`/api/openapi/storefront.yaml`](/api/openapi/storefront.yaml) (605 KB). Includes all response schemas, examples, security requirements, and error shapes. ## Platform API — admin surface Full CRUD on products, variants, stock, orders, users, taxes, shipping, promotions, reports. OAuth2-gated with `admin` scope. Issued via `client_credentials` grant by the webmaster. Full spec: [`/api/openapi/platform.yaml`](/api/openapi/platform.yaml) (755 KB). ## OAuth 2.0 — authentication Issuer: `https://spree.apparel.monster` Token endpoint: `/spree_oauth/token` Authorization endpoint: `/spree_oauth/authorize` Revocation endpoint: `/spree_oauth/revoke` Discovery: [`/.well-known/oauth-authorization-server`](/.well-known/oauth-authorization-server) Grants: `authorization_code` (with PKCE S256), `password`, `client_credentials`, `refresh_token`. Scopes: `read`, `write`, `admin`. Full spec: [`/api/openapi/oauth.yml`](/api/openapi/oauth.yml). See [authentication walkthrough](authentication.md). ## Rate limits Response headers on all successful calls: - `X-RateLimit-Limit: 60` - `X-RateLimit-Remaining: 60` - `X-RateLimit-Reset: 60` - `X-RateLimit-Policy: 60;w=60` (60 requests per 60-second rolling window) On a 429, honor `Retry-After: `. Our current policy gives clients ~5 seconds of backoff minimum after a throttle. ## Error responses All `/api/*` endpoints return JSON errors with this shape: ```json { "error": "not_found", "code": 404, "message": "Resource not found. Consult /.well-known/api-catalog for the canonical API surface.", "retry_after_seconds": 5, "documentation": "https://spree.apparel.monster/api/openapi/storefront.yaml" } ``` Validation errors (422) carry per-field reasons: ```json { "errors": { "email": ["can't be blank"], "ship_address": { "zipcode": ["is not a valid postal code"] } } } ``` ## Service status Machine-readable: [`/status`](/status) — returns JSON with service state, current rate-limit policy, and incidents. ## See also - [`/quickstart.md`](/docs/quickstart.md) — code to copy-paste into your agent in 60 seconds. - [`/authentication.md`](/docs/authentication.md) — auth flows with step-by-step curl examples. - [`/llms.txt`](/llms.txt) — LLM-friendly overview. - [`/?mode=agent`](/?mode=agent) — machine-readable homepage summary. - [`/.well-known/api-catalog`](/.well-known/api-catalog) — RFC 9727 link-set.