# XHG Home & Garden — Guide for AI agents

> XHG Home & Garden (XHG) is an Australian online store for garden and home décor (garden statues and ornaments, cast iron and recycled metal art, pots and planters, wall art, signs, bells, bookends and more) at https://xhg.com.au. Prices are in AUD and include GST. We deliver within Australia only, dispatching from Canley Heights, NSW.

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://xhg.com.au/api/agent/products?q=metal+frog&max_price=150`
2. Details: `GET https://xhg.com.au/api/agent/products/{slug-or-sku}`
3. Shipping: `GET https://xhg.com.au/api/agent/shipping?postcode=2000&items={sku}:1` (e.g. `items=XHG-38594:1`)

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

## MCP server

Agents that support the Model Context Protocol can connect to `https://xhg.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`.

Example client config:

```json
{
  "mcpServers": {
    "xhg": { "type": "http", "url": "https://xhg.com.au/mcp" }
  }
}
```

## Top-level categories

- [Artificial Plants](https://xhg.com.au/category/artificial-plants) — `category=artificial-plants`
- [Clocks](https://xhg.com.au/category/clocks) — `category=clocks`
- [Flashlights](https://xhg.com.au/category/flashlights) — `category=flashlights`
- [Furniture](https://xhg.com.au/category/furniture) — `category=furniture`
- [Garden Ornaments & Statues](https://xhg.com.au/category/garden-ornaments-statues) — `category=garden-ornaments-statues`
- [Garden Outdoor](https://xhg.com.au/category/garden-outdoor) — `category=garden-outdoor`
- [Glass Statues & Ornaments](https://xhg.com.au/category/glass-statues-ornaments) — `category=glass-statues-ornaments`
- [Home](https://xhg.com.au/category/home) — `category=home`
- [Lighting](https://xhg.com.au/category/lighting) — `category=lighting`
- [Pedestals, Stools & Stands](https://xhg.com.au/category/pedestals-stools-stands) — `category=pedestals-stools-stands`
- [Pets](https://xhg.com.au/category/pets) — `category=pets`
- [Recycled / Scrap Metal Garden Art & Sculptures](https://xhg.com.au/category/recycled-scrap-metal-garden-art-sculptures) — `category=recycled-scrap-metal-garden-art-sculptures`
- [Signs & Plaques](https://xhg.com.au/category/signs-plaques) — `category=signs-plaques`
- [Wall Decor & Hangings](https://xhg.com.au/category/wall-decor-hangings) — `category=wall-decor-hangings`
- [Wall Hooks & Brackets](https://xhg.com.au/category/wall-hooks-brackets) — `category=wall-hooks-brackets`

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 ("metal frog", "gnome", "hanging planter") rather than full sentences. |
| `category` | Category slug from `/api/agent/categories`. Includes sub-categories. |
| `brand` | Exact brand name, case-insensitive (e.g. `Think Outside`, `Alfresco`, `EEIEEIO`). |
| `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), the supplier spec sheet as `specifications` (titled sections of label/value rows such as material, theme, colour, indoor/outdoor use and sizes), 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, and a `productCount` per category.

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

Live delivery cost to an Australian postcode, the same courier 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. Adding `suburb` alongside `postcode` gives the most exact price. |
| `items` | Comma-separated `SKU:quantity` pairs, e.g. `XHG-38594:1,XHG-29887:2`. Up to 20 items. |

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

Shipping is priced live by courier for the whole order, so quote every item the shopper is buying together rather than adding up single-item quotes. The response gives a `total` (the cheapest courier service for all items), every courier option in `services` (cheapest first, with `estimatedDays` when the courier gives an estimate, otherwise null), and a per-item list where `shippable: false` marks an unknown SKU. Bulky items (`shipping.palletised` on the product) ship as pallet freight and cost more. 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.

## Buying guides

- [Cast iron garden ornaments: choosing, placing and caring for them](https://xhg.com.au/blog/cast-iron-garden-ornaments-guide)
- [Recycled metal garden art: what it is and how to style it](https://xhg.com.au/blog/recycled-metal-garden-art-guide)
- [How to choose pots and planters for Australian gardens](https://xhg.com.au/blog/choosing-pots-and-planters-guide)

More at [https://xhg.com.au/blog](https://xhg.com.au/blog).

## Policies

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

Contact: orders@xhg.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://xhg.com.au/sitemap.xml) for discovery.