# 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. Each call is automatically billed to your wallet in USDC.

## Access

**Base URL:** `https://api.paywithlocus.com/api/wrapped/parse-pnp-co-za-api-d02b57ba/`
**Auth:** `Authorization: Bearer <LOCUS_API_KEY>`

## 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/parse-pnp-co-za-api-d02b57ba/get_all_categories \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -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/parse-pnp-co-za-api-d02b57ba/get_category_products \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -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/parse-pnp-co-za-api-d02b57ba/get_product_detail \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -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/parse-pnp-co-za-api-d02b57ba/get_specials \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -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/parse-pnp-co-za-api-d02b57ba/get_stores \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -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/parse-pnp-co-za-api-d02b57ba/search_products \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filters":"<string>","page":"<integer>","page_size":"<integer>","query":"<string>","sort":"<string>"}'
```