# The Good Guys — Wrapped API

> **You are on:** `https://api.beta.paywithlocus.com/api` | [llms.txt](https://beta.paywithlocus.com/llms.txt) | [docs](https://docs.paywithlocus.com)
>
> Locus runs on multiple environments -- make sure every URL you call matches your expected environment.
> | Environment | Landing | API | Docs |
> |---|---|---|---|
> | Production | paywithlocus.com | api.paywithlocus.com | docs.paywithlocus.com |
> | Beta | beta.paywithlocus.com | api.beta.paywithlocus.com | docs.paywithlocus.com |
> | Stage | stage.paywithlocus.com | api.stage.paywithlocus.com | docs.paywithlocus.com |
>
> If the API URL above doesn't match your expected environment, re-fetch this file from the correct domain.

> Search and browse The Good Guys' complete product catalog with detailed tech specs and customer reviews, then find nearby stores and check delivery options for your purchases. Discover deals, filter by category or brand, and access everything you need to shop electronics and appliances with confidence.

**Category:** E-commerce | **Website:** [thegoodguys.com.au/](https://thegoodguys.com.au/) | **Docs:** [parse.bot/marketplace/7c344021-d4df-49e6-aa20-35153c5ce34d/thegoodguys-com-au-api](https://parse.bot/marketplace/7c344021-d4df-49e6-aa20-35153c5ce34d/thegoodguys-com-au-api)

Pay-per-use API proxy for Locus Pro. Each call burns credits from your workspace balance.

## Access

**Base URL:** `https://api.beta.paywithlocus.com/api/wrapped/credits/the-good-guys/`
**Auth:** `Authorization: Bearer <LOCUS_CREDITS_SECRET_KEY>` (an `lcr_` secret key or a scoped `lcac_` agent credential)
**Required header:** `Idempotency-Key: <fresh UUID per call>`. A retry with the same key replays the stored result without a new charge.
**Response:** the provider response after any endpoint-specific normalization. `X-Locus-Credits-Charged` carries the charge and `X-Locus-Credits-Balance` the remaining balance. Insufficient credits return `402` before the provider is called.
**Pricing:** estimated costs below are USD. Locus debits the credit equivalent at your workspace rate.

Full call contract: https://docs.paywithlocus.com/api-reference/introduction

> Using a Pay With Locus wallet key (`claw_` prefix)? Wallet routes are documented separately: https://docs.paywithlocus.com/wrapped-apis/for-agents

## Endpoints

### Get brand products

Get products from a specific brand. Returns paginated results filtered by vendor/brand name. Brand name must match exactly as returned from get_brands.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `brand_name` | string | Yes | Brand name exactly as returned from get_brands (e.g. 'Samsung', 'Apple', 'LG', 'Hisense') |
| `limit` | integer | No | Results per page |
| `page` | integer | No | Page number (0-based) |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/the-good-guys/get-brand-products \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"brand_name":"<string>","limit":"<integer>","page":"<integer>"}'
```

### Get brands

Retrieve the list of all available brands with product counts. Returns brands sorted alphabetically. No input parameters required.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/the-good-guys/get-brands \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### Get category listing

Retrieve products in a given category or subcategory. Accepts a category handle (as returned from get_category_tree) and returns paginated product results filtered by that category. Tries lvl0 first, then falls back to lvl1 matching.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `category_handle` | string | Yes | Category handle as returned from get_category_tree (e.g. 'televisions', 'audio', 'laundry', 'phones-and-wearables') |
| `limit` | integer | No | Results per page |
| `page` | integer | No | Page number (0-based) |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/the-good-guys/get-category-listing \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"category_handle":"<string>","limit":"<integer>","page":"<integer>"}'
```

### Get category tree

Retrieve the full category hierarchy with product counts. Returns top-level categories (lvl0) and their subcategories (lvl1). Each category includes a name (usable as category_handle in get_category_listing), count, and subcategories array.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/the-good-guys/get-category-tree \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### Get deals

Fetch current active deals and clearance products. Returns paginated results of products currently on sale or clearance. Tries the 'deals' collection first, then falls back to 'clearance' if empty.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `limit` | integer | No | Results per page |
| `page` | integer | No | Page number (0-based) |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/the-good-guys/get-deals \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"limit":"<integer>","page":"<integer>"}'
```

### Get delivery options

Get delivery options, costs, and store stock availability for a product and postcode. Resolves the SKU to product details and the postcode to coordinates internally, then queries the delivery API. Returns fulfilment options and nearby store stock status.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `postcode` | string | Yes | Australian 4-digit postcode (e.g. '3000') |
| `sku` | string | Yes | Product SKU/item number (e.g. '50094438') from search or product detail results |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/the-good-guys/get-delivery-options \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"postcode":"<string>","sku":"<string>"}'
```

### Get product detail

Fetch full product details by handle or URL. Returns the complete product object including specs, a sample of up to 10 recent reviews, pricing, and metadata. At least one of handle or url must be provided. If url is provided, the handle is extracted from it automatically.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `handle` | string | No | Product handle/slug from product URL (e.g. 'samsung-65-inches-ls03f-the-frame-pro-neo-qled-4k-mini-led-smart-ai-tv-2025-qa65ls03fwwxxy') |
| `url` | string | No | Full product URL; handle will be extracted from it |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/the-good-guys/get-product-detail \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"handle":"<string>","url":"<string>"}'
```

### Get product reviews

Get customer reviews for a specific product SKU. Returns paginated reviews with rating, title, text, reviewer name, and recommendation status. SKU can be obtained from search or product detail results.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `limit` | integer | No | Reviews per page |
| `page` | integer | No | Page number (0-based) |
| `sku` | string | Yes | Product SKU/item number (e.g. '50094438') from search or product detail results |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/the-good-guys/get-product-reviews \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"limit":"<integer>","page":"<integer>","sku":"<string>"}'
```

### Get store locator

Find nearby stores by Australian postcode. Returns the closest stores with address, phone number, opening hours, and distance in kilometers. Resolves postcode to coordinates internally.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `postcode` | string | Yes | Australian 4-digit postcode (e.g. '3000', '2000', '4000') |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/the-good-guys/get-store-locator \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"postcode":"<string>"}'
```

### Search products

Full-text search over The Good Guys product catalog. Returns paginated results ranked by relevance. Each product includes title, price, SKU, handle, vendor, image URL, category hierarchy, and technical specifications. Paginates via a zero-based page parameter.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `limit` | integer | No | Results per page |
| `page` | integer | No | Page number (0-based) |
| `query` | string | Yes | Search keyword (e.g. 'samsung tv', 'laptop', 'washing machine') |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/the-good-guys/search-products \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"limit":"<integer>","page":"<integer>","query":"<string>"}'
```

## Next steps

- [All wrapped API providers](https://beta.paywithlocus.com/wapi/index.md): pick another provider.
- [Find and call tools](https://beta.paywithlocus.com/agent/tools.md): price ceilings, async results, and errors.
- [Credits and billing](https://beta.paywithlocus.com/agent/billing.md): what a call costs and how to add credits.
- [Agent docs index](https://beta.paywithlocus.com/agent/index.md): every Locus agent page.