# Coles — 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 Coles supermarket products by category, view detailed product information, and discover current specials all in one place. Find exactly what you're looking for with powerful search functionality and organized category navigation.

**Category:** Food & Dining | **Website:** [coles.com.au/](https://coles.com.au/) | **Docs:** [parse.bot/marketplace/5d43bf47-ad1e-40fa-b2b0-b5fed94522bd/coles-com-au-api](https://parse.bot/marketplace/5d43bf47-ad1e-40fa-b2b0-b5fed94522bd/coles-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/coles/`
**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 all categories

Retrieve the full category tree with up to 3 levels of nesting. Each category includes an id, name, seoToken (slug for URL construction), and nested catalogGroupView array of child categories. Use seoToken values as input to get_category_products and get_subcategory_products.

**Estimated cost:** Metered

_No parameters required._

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

### Get category products

Browse products within a top-level category. Categories are identified by their slug (seoToken) from the category tree. Returns a paginated list of up to 48 products per page.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `category` | string | Yes | Category slug from the category tree (seoToken field). Examples: 'fruit-vegetables', 'drinks', 'pantry', 'dairy-eggs-fridge'. |
| `page` | integer | No | Page number for pagination. |

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

### Get product details

Retrieve full details for a single product by its slug. The slug is available in results from search_products, get_category_products, get_subcategory_products, or get_specials. Returns detailed information including nutritional data, ingredients, allergens, and storage instructions when available.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `slug` | string | Yes | Product slug from search or browse results. Format: brand-name-size-id (e.g. 'coles-full-cream-milk-3l-8150288'). |

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

### Get specials

Retrieve current specials and promotional products across all categories. Returns a paginated list of discounted products, each including current price and original (was) price. Up to 48 products per page.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `page` | integer | No | Page number for pagination. |

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

### Get subcategory products

Browse products within a subcategory nested under a parent category. Both parent and subcategory are identified by their slugs (seoToken) from the category tree. Returns a paginated list of up to 48 products per page.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `category` | string | Yes | Parent category slug (seoToken). Example: 'fruit-vegetables'. |
| `page` | integer | No | Page number for pagination. |
| `subcategory` | string | Yes | Subcategory slug (seoToken) under the parent category. Example: 'fruit'. |

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

### Search products

Full-text search across the Coles product catalog. Matches product name, brand, and description. Returns a paginated list of products sorted by relevance. Each page contains up to 48 products.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `page` | integer | No | Page number for pagination. |
| `query` | string | Yes | Search keyword to match against product name, brand, and description. |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/coles/search-products \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"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.