# Pick n Pay — 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.

> Search for groceries, browse products by category, and discover current specials at Pick n Pay stores, while accessing detailed product information, store locations, and fresh produce availability all in one place.

**Category:** Food & Dining | **Website:** [pnp.co.za/](https://pnp.co.za/) | **Docs:** [parse.bot/marketplace/d02b57ba-b2fd-4a71-96b1-b2084ceda061/pnp-co-za-api](https://parse.bot/marketplace/d02b57ba-b2fd-4a71-96b1-b2084ceda061/pnp-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/pick-n-pay/`
**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 top-level department categories available for product browsing. Returns category codes usable with get_category_products and link names for display. No input parameters required.

**Estimated cost:** Metered

_No parameters required._

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

### Get category products

List all products within a specific category. Returns products, facets for sub-category refinement, pagination metadata, and breadcrumbs showing the category hierarchy. Category IDs are obtainable from get_all_categories or from facets in search results.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `category_id` | string | Yes | Category ID (e.g. 'beverages-423144840', 'food-cupboard-423144840'). Obtain from get_all_categories or search_products facets. |
| `filters` | string | No | Additional filter string appended to the category query |
| `page` | integer | No | Page number (0-based) |
| `page_size` | integer | No | Number of results per page |
| `sort` | string | No | Sort order |

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

### Get product detail

Retrieve full product details by product code. Returns comprehensive information including images at multiple resolutions, description, nutritional info via classifications, stock levels with exact quantities, pricing with promotion details, category path, and variant options. Product codes are available from search or category listing results.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `product_code` | string | Yes | Product code from search or category results (e.g. '000000000000349246_EA') |

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

### Get specials

List products currently on promotion across the store or within a specific category. Returns promotional products with current and previous pricing, savings amounts, and promotion descriptions. Supports pagination.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `category_id` | string | No | Category to filter specials by (e.g. 'beverages-423144840'). Defaults to all products. |
| `page` | integer | No | Page number (0-based) |
| `page_size` | integer | No | Number of results per page |

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

### Get stores

Search for Pick n Pay store locations. Returns all stores when no query is provided, or filters by name, city, suburb, or street address. Each store includes address, contact details, trading hours, geolocation coordinates, and store type (e.g. SUPER, CLOTHING, EXPRESS).

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `query` | string | No | Search term to filter stores by name, city, suburb, or street (e.g. 'sandton', 'cape town'). Omitting returns all stores. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/pick-n-pay/get-stores \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"query":"<string>"}'
```

### Search products

Full-text search over Pick n Pay's product catalog. Matches against product names and descriptions. Supports pagination, sorting by relevance or price, and filtering by category, certification, or promotion status. Each product in results carries pricing, stock status, and image URLs. Facets in the response enumerate available refinement dimensions with hit counts.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `filters` | string | No | Additional filter string appended to the search query (e.g. ':isOnPromotion:On+Promotion') |
| `page` | integer | No | Page number (0-based) |
| `page_size` | integer | No | Number of results per page |
| `query` | string | Yes | Search keyword (e.g. 'milk', 'bread') |
| `sort` | string | No | Sort order |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/pick-n-pay/search-products \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"filters":"<string>","page":"<integer>","page_size":"<integer>","query":"<string>","sort":"<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.