# CoolStuff2Buy (CS2B) — Guide for AI agents

> CoolStuff2Buy is an Australian online store (https://cs2b.com.au) selling a wide range of products for the home, garden, outdoors, pets, kids and more. Prices are in AUD and include GST. We deliver within Australia only.

This guide explains how AI agents and assistants can search our catalogue, read product details and get live shipping quotes. All endpoints below are public, read-only, return JSON and need no authentication.

**Scope:** only product catalogue data is available. Orders, customers, accounts and payments are not exposed and agents cannot place orders through the API — send shoppers to the product page (`url` field) to buy.

## Quick start

1. Search: `GET https://cs2b.com.au/api/agent/products?q=standing+desk&max_price=300`
2. Details: `GET https://cs2b.com.au/api/agent/products/{slug-or-sku}`
3. Shipping: `GET https://cs2b.com.au/api/agent/shipping?postcode=2000&items={sku}:1`

Full schema: [OpenAPI spec](https://cs2b.com.au/api/agent/openapi.json)

## MCP server

Agents that support the Model Context Protocol can connect to `https://cs2b.com.au/mcp` (Streamable HTTP, no authentication) instead of calling the HTTP API. It offers the same data as read-only tools: `search_products`, `get_product`, `list_categories` and `quote_shipping`.

## Top-level categories

- [Appliances](https://cs2b.com.au/category/appliances) — `category=appliances`
- [Audio & Video](https://cs2b.com.au/category/audio-video) — `category=audio-video`
- [Auto Accessories](https://cs2b.com.au/category/auto-accessories) — `category=auto-accessories`
- [Baby & Kids](https://cs2b.com.au/category/baby-kids) — `category=baby-kids`
- [Commercial](https://cs2b.com.au/category/commercial) — `category=commercial`
- [Electronics](https://cs2b.com.au/category/electronics) — `category=electronics`
- [Fashion](https://cs2b.com.au/category/fashion) — `category=fashion`
- [Food & Beverage](https://cs2b.com.au/category/food-beverage) — `category=food-beverage`
- [Furniture](https://cs2b.com.au/category/furniture) — `category=furniture`
- [Gift & Novelty](https://cs2b.com.au/category/gift-novelty) — `category=gift-novelty`
- [Hampers](https://cs2b.com.au/category/hampers) — `category=hampers`
- [Health & Beauty](https://cs2b.com.au/category/health-beauty) — `category=health-beauty`
- [Home & Garden](https://cs2b.com.au/category/home-garden) — `category=home-garden`
- [Occasions](https://cs2b.com.au/category/occasions) — `category=occasions`
- [Outdoor Recreation](https://cs2b.com.au/category/outdoor-recreation) — `category=outdoor-recreation`
- [Pet Care](https://cs2b.com.au/category/pet-care) — `category=pet-care`
- [Sports & Fitness](https://cs2b.com.au/category/sports-fitness) — `category=sports-fitness`
- [Tools](https://cs2b.com.au/category/tools) — `category=tools`

Sub-categories are listed at `/api/agent/categories`.

## Endpoints

### Search products — `GET /api/agent/products`

At least one of `q`, `category` or `brand` is required.

| Param | Description |
| --- | --- |
| `q` | Keywords. Every word must match the title, brand or SKU. Use short, specific nouns ("bar stool", "dog bed") rather than full sentences. |
| `category` | Category slug from `/api/agent/categories`. Includes sub-categories. |
| `brand` | Exact brand name, case-insensitive (e.g. `Gardeon`). |
| `min_price`, `max_price` | Price bounds in AUD, applied to the current (sale) price. |
| `sort` | `relevance` (default with `q`), `price_asc`, `price_desc`, `newest`. |
| `include_out_of_stock` | `true` to include sold-out products. Default: in-stock only. |
| `page`, `limit` | Pagination. `limit` max 50, default 20. Follow `nextPage` while `hasMore` is true. |

Each result has `sku`, `slug`, `title`, `brand`, a short `summary`, `price`, `inStock`, `freeShipping`, `image`, the customer-facing `url` and a `detailsUrl`.

### Product details — `GET /api/agent/products/{slug-or-sku}`

Returns the full plain-text `description`, `price` (with `compareAt`, `onSale` and `saleEndsAt`), `inStock`, `categories`, all `images`, `specs` (weight in kg, dimensions in cm, EAN barcode), colour/size `variants` with their own SKUs, and `shipping` with indicative rates per delivery zone.

### Categories — `GET /api/agent/categories`

The category tree with slugs for the `category` search filter.

### Shipping quote — `GET /api/agent/shipping`

Live delivery cost to an Australian postcode, the same calculation used at checkout.

| Param | Description |
| --- | --- |
| `postcode` | 4-digit Australian postcode (preferred). |
| `suburb`, `state` | Alternative to `postcode`, e.g. `suburb=Parramatta&state=NSW`. Check `resolvedFrom` in the response, since suburb names can be ambiguous. |
| `items` | Comma-separated `SKU:quantity` pairs, e.g. `V63-123:1,GA-456:2`. Up to 20 items. |

`POST /api/agent/shipping` accepts the same fields as JSON with `items: [{ "sku": "...", "quantity": 1 }]`.

The response gives a `total` and a per-item breakdown. Shipping is charged per item, so multiply-quantity orders cost more. Items with `shippable: false` cannot be delivered to that postcode. Quotes are limited to 30 per minute per client.

## Prices and money

- All amounts are AUD strings with two decimals (e.g. `"129.95"`); `price.cents` holds the integer value.
- Prices include 10% GST.
- `price.compareAt` is the was-price or RRP when it is higher than the current price.

## Policies

- [Shipping policy](https://cs2b.com.au/shipping-policy)
- [Returns and refunds](https://cs2b.com.au/returns-and-refunds)
- [Terms and conditions](https://cs2b.com.au/terms-and-conditions)
- [Privacy policy](https://cs2b.com.au/privacy-policy)
- [About us](https://cs2b.com.au/about)

Contact: sales@cs2b.com.au

## Guidelines for agents

- Always link shoppers to the product `url` to purchase; checkout happens on the website.
- Quote prices and stock from the API at the time of the conversation; they change daily.
- Present shipping from `/api/agent/shipping` as an estimate confirmed at checkout.
- Cache search and product responses for up to 5 minutes; do not crawl the full catalogue through the API — use the [sitemap](https://cs2b.com.au/sitemap.xml) for discovery.