# Woolworths (South Africa) — Wrapped API

> **You are on:** `https://api.paywithlocus.com/api` | [llms.txt](https://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.

> Browse Woolworths South Africa's food categories and search for specific products while accessing detailed nutritional information and weight-based pricing. Find store locations across the country by province and suburb to check availability and plan your shopping trips.

**Category:** Food & Dining | **Website:** [woolworths.co.za/](https://woolworths.co.za/) | **Docs:** [parse.bot/marketplace/94630827-cc4b-4199-91d9-1bf19c8132c3/woolworths-co-za-api](https://parse.bot/marketplace/94630827-cc4b-4199-91d9-1bf19c8132c3/woolworths-co-za-api)

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

## Access

**Base URL:** `https://api.paywithlocus.com/api/wrapped/credits/woolworths-south-africa/`
**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 food categories

Retrieves all top-level food categories from Woolworths via Constructor.io browse API. Each category includes a name and group_id suitable for use with get_product_listing. Categories include seasonal collections, product types (Bakery, Frozen Food), and dietary preferences.

**Estimated cost:** Metered

_No parameters required._

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

### Get product details

Retrieves comprehensive product information including nutritional data, ingredients, allergens, dietary info, images, brand, rating, review count, and pricing. Use the product URL path from search_products or get_product_listing results.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `product_url` | string | Yes | Product URL path from search_products or get_product_listing results (e.g. '/prod/Food/Meat-Poultry-Fish/Poultry/Crumbed/Crumbed-Chicken-Schnitzels-Avg-650-g/_/A-2034180000008'). |

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

### Get product listing

Retrieves a paginated list of products for a given category. Returns up to 24 products per page with pricing. Use offset to paginate (increments of 24). Each product includes id, name, url, price, price_per_kg, review_count, promo_label, and on_sale flag.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `category_url` | string | Yes | Category group_id from get_food_categories (e.g. 'ncat0010251', 'cat606522'). |
| `offset` | integer | No | Pagination offset. Results come in pages of 24. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/woolworths-south-africa/get-product-listing \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"category_url":"<string>","offset":"<integer>"}'
```

### Get store locator provinces

Retrieves all South African provinces available in the Woolworths store locator. Each province includes an ID, name, and flags for store pickup and liquor delivery availability.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/woolworths-south-africa/get-store-locator-provinces \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### Get store locator suburbs

Retrieves all suburbs with their IDs and postal codes for the Woolworths store locator. Use suburb IDs with get_stores_by_suburb to find nearby stores. Returns a large list of suburbs across all provinces.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/woolworths-south-africa/get-store-locator-suburbs \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### Get stores by suburb

Retrieves Woolworths stores within a specified radius of a suburb. Returns store names, addresses, and phone numbers. Use suburb IDs from get_store_locator_suburbs.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `distance` | integer | No | Search radius in km. |
| `suburb_id` | string | Yes | Suburb ID from get_store_locator_suburbs (e.g. '489', '462'). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/woolworths-south-africa/get-stores-by-suburb \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"distance":"<integer>","suburb_id":"<string>"}'
```

### Search products

Full-text search for food products by keyword via Constructor.io. Returns a paginated list of matching products (up to 24 per page) with prices. Use offset to paginate through results in increments of 24.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `offset` | integer | No | Pagination offset. Results come in pages of 24. |
| `query` | string | Yes | Search query (e.g. 'chicken', 'bread', 'organic'). |

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

## Next steps

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