# PAK'nSAVE & New World API — New Zealand grocery prices per store from paknsave.co.nz and newworld.co.nz: NZD price, Clubcard price, multi-buys, unit price, sold-by-weight, availability, ingredients, allergens, nutrition, categories and stores

> Search one PAK'nSAVE or New World store's online range: price in NZD, club-card price kept apart from the price, multi-buy, unit price, sold-by-weight details, online / in-store availability, dietary tags and every category placement per product. `query` or `category` is required (either one); filter by brand, dietary tag or deals.
> ReefAPI engine `paknsave` · 5 endpoints · clean JSON, no scraping or browsers to manage.

## How to call
- **Endpoint:** `POST https://api.reefapi.com/paknsave/v1/<action>` with a JSON body.
- **Auth:** header `x-api-key: <YOUR_REEFAPI_KEY>` — create one free (1,000 credits, no card): https://reefapi.com/signup
- **Response (every call):** `{ ok: boolean, data: ..., meta: { record_count, credits, ... }, error: { code, message } }` — branch on `ok`. Failed calls are free except verified SHEIN NOT_FOUND on product/detail and price (4 credits).
- **One key + one shared credit pool** across every ReefAPI API. Per-call credits are listed on each endpoint below.
- **Use it from an AI agent (MCP):** connect `https://api.reefapi.com/mcp` (remote streamable-http). Send the key as `Authorization: Bearer <key>`, or put it in the URL (`?key=<key>`) when the client has no header field, as ChatGPT does.

## Endpoints

### POST https://api.reefapi.com/paknsave/v1/search — 2 credits
Search one PAK'nSAVE or New World store's online range: price in NZD, club-card price kept apart from the price, multi-buy, unit price, sold-by-weight details, online / in-store availability, dietary tags and every category placement per product. `query` or `category` is required (either one); filter by brand, dietary tag or deals.

**Parameters:**
- `query` (string, optional) — What to search for, as typed in the site's search box. Required unless category is given.
- `category` (string, optional) — Category path from the `categories` action, 1-3 levels joined by ' > ' (e.g. 'Pantry' or 'Fridge, Deli & Eggs > Milk > Fresh Milk'). Case-insensitive.
- `store_id` (string, optional) — Store whose prices, deals and range you want: a store_id from the `stores` action, or part of a store name ('Napier', 'Royal Oak'). Prices differ by store. Without it the default store is used (PAK'nSAVE Royal Oak / New World Remuera, Auckland) and the answer says so (store_defaulted: true).
- `banner` (enum, optional, default "paknsave") — Which Foodstuffs shop: paknsave (default) or newworld. Same platform, own stores, prices and deals; New World has Clubcard prices. [one of: paknsave, newworld]
- `brand` (string, optional) — Only this brand, as a row's `brand` field gives it (case-insensitive).
- `dietary` (string, optional) — Only products with this dietary tag, as a row's `dietary` list gives it (e.g. Gluten Free, Vegan, Vegetarian, Non-GMO, Low Fat, Low Sugar).
- `on_promotion` (boolean, optional, default false) — Only products on a deal at this store (sale price, multi-buy or club-card price).
- `sort` (enum, optional, default "relevance") — Order of the results. [one of: relevance, price_asc, price_desc, unit_price_asc, unit_price_desc]
- `page` (integer, optional, default 1) — Page number, 1-20, 50 products per page. The source shows at most the first 1000 products of a result (total_capped says when).

**Returns:** banner, store_id, store_name, store_region, store_defaulted, query, category, brand, dietary, on_promotion, sort, total, total_is_exact, total_capped, total_on_promotion (deals), page, page_size, last_page, has_more, returned, products[]{rank, product_id, title, name, brand, size, price (NZD, what everybody pays for one now), regular_price (the source's price without a limited single-unit deal), price_limit, currency, on_promotion, member_price (club-card single-unit price, apart from price), member_price_program, member_unit_price, member_price_limit, multi_buy{quantity, price, text, card_required, mix_and_match, limit, promotion_id}, price_unit ('each' | 'kg'), unit_price{price, quantity, unit, per, text}, sold_by ('unit' | 'weight' | 'unit_or_weight'), weight{average_piece_g, min_order_g, step_g}, available_online, available_in_store, promotions[]{promotion_id, reward_type, quantity, deal_price, card_required, limit, multi_products, best, text, unit_price}, categories[] (every placement, 'A > B > C'), dietary[], origin, restricted, liquor, tobacco, store_id, url}

**Example request body:**
```json
{
  "query": "milk"
}
```

### POST https://api.reefapi.com/paknsave/v1/deals — 2 credits
Everything on a deal at one store (the site's Deals page): sale prices, multi-buys and club-card prices, optionally narrowed by query, category, brand or dietary tag. Reports the store's own count of deals (total_on_promotion) beyond the 1000-row window.

**Parameters:**
- `query` (string, optional) — Optional text to narrow the deals.
- `category` (string, optional) — Category path from the `categories` action, 1-3 levels joined by ' > ' (e.g. 'Pantry' or 'Fridge, Deli & Eggs > Milk > Fresh Milk'). Case-insensitive.
- `store_id` (string, optional) — Store whose prices, deals and range you want: a store_id from the `stores` action, or part of a store name ('Napier', 'Royal Oak'). Prices differ by store. Without it the default store is used (PAK'nSAVE Royal Oak / New World Remuera, Auckland) and the answer says so (store_defaulted: true).
- `banner` (enum, optional, default "paknsave") — Which Foodstuffs shop: paknsave (default) or newworld. Same platform, own stores, prices and deals; New World has Clubcard prices. [one of: paknsave, newworld]
- `brand` (string, optional) — Only this brand, as a row's `brand` field gives it (case-insensitive).
- `dietary` (string, optional) — Only products with this dietary tag, as a row's `dietary` list gives it (e.g. Gluten Free, Vegan, Vegetarian, Non-GMO, Low Fat, Low Sugar).
- `sort` (enum, optional, default "relevance") — Order of the results. [one of: relevance, price_asc, price_desc, unit_price_asc, unit_price_desc]
- `page` (integer, optional, default 1) — Page number, 1-20, 50 products per page. The source shows at most the first 1000 products of a result (total_capped says when).

**Returns:** banner, store_id, store_name, store_region, store_defaulted, query, category, brand, dietary, on_promotion, sort, total, total_is_exact, total_capped, total_on_promotion (deals), page, page_size, last_page, has_more, returned, products[]{rank, product_id, title, name, brand, size, price (NZD, what everybody pays for one now), regular_price (the source's price without a limited single-unit deal), price_limit, currency, on_promotion, member_price (club-card single-unit price, apart from price), member_price_program, member_unit_price, member_price_limit, multi_buy{quantity, price, text, card_required, mix_and_match, limit, promotion_id}, price_unit ('each' | 'kg'), unit_price{price, quantity, unit, per, text}, sold_by ('unit' | 'weight' | 'unit_or_weight'), weight{average_piece_g, min_order_g, step_g}, available_online, available_in_store, promotions[]{promotion_id, reward_type, quantity, deal_price, card_required, limit, multi_products, best, text, unit_price}, categories[] (every placement, 'A > B > C'), dietary[], origin, restricted, liquor, tobacco, store_id, url}

**Example request body:**
```json
{
  "banner": "newworld",
  "query": "chocolate"
}
```

### POST https://api.reefapi.com/paknsave/v1/product — 1 credit
One product at one store: price, club-card price, multi-buy with start / end dates, unit price, barcode (or PLU for weighed goods), description, ingredients, allergens, nutrition panel, dietary tags, origin, images and availability. NOT_FOUND when the store does not sell it.

**Parameters:**
- `product_id` (string, required) — The product_id of a search row (e.g. 5201490-EA-000, 5046542-KGM-000) or the product page URL.
- `store_id` (string, optional) — Store whose prices, deals and range you want: a store_id from the `stores` action, or part of a store name ('Napier', 'Royal Oak'). Prices differ by store. Without it the default store is used (PAK'nSAVE Royal Oak / New World Remuera, Auckland) and the answer says so (store_defaulted: true).
- `banner` (enum, optional, default "paknsave") — Which Foodstuffs shop: paknsave (default) or newworld. Same platform, own stores, prices and deals; New World has Clubcard prices. [one of: paknsave, newworld]

**Returns:** banner, store_id, store_name, store_region, store_defaulted, product{product_id, title, name, brand, size, net_content, price, regular_price, price_limit, currency, on_promotion, member_price, member_price_program, member_unit_price, member_price_limit, multi_buy{…}, non_member_price, price_unit, unit_price{…}, price_valid_text, sold_by, weight{…}, available_online, available_in_store, fulfilment[]{method, available}, promotions[]{promotion_id, reward_type, quantity, deal_price, card_required, limit, multi_products, text, starts, ends, linked_products[]}, barcode, plu, description, ingredients, allergens, nutrition{servings_per_pack, nutrients[]{nutrient, code, value, unit, basis, basis_quantity, basis_unit, precision, serving_size}}, categories[], category_paths[], dietary[], origin, in_store_made, restricted, images[], image_sizes{}, store_id, url}

**Example request body:**
```json
{
  "product_id": "5010431-EA-000"
}
```

### POST https://api.reefapi.com/paknsave/v1/categories — 2 credits
The category tree of one store (names and paths to pass as `category`).

**Parameters:**
- `store_id` (string, optional) — Store whose prices, deals and range you want: a store_id from the `stores` action, or part of a store name ('Napier', 'Royal Oak'). Prices differ by store. Without it the default store is used (PAK'nSAVE Royal Oak / New World Remuera, Auckland) and the answer says so (store_defaulted: true).
- `banner` (enum, optional, default "paknsave") — Which Foodstuffs shop: paknsave (default) or newworld. Same platform, own stores, prices and deals; New World has Clubcard prices. [one of: paknsave, newworld]

**Returns:** banner, store_id, store_name, store_defaulted, departments, total_categories, categories[]{name, path, level, children[]}

**Example request body:**
```json
{
  "banner": "paknsave"
}
```

### POST https://api.reefapi.com/paknsave/v1/stores — 2 credits
PAK'nSAVE or New World store directory: store_id, name, address, island, coordinates, phone, opening hours, click & collect / delivery. Narrow by text or island, or sort by distance from a point.

**Parameters:**
- `banner` (enum, optional, default "paknsave") — Which Foodstuffs shop: paknsave (default) or newworld. Same platform, own stores, prices and deals; New World has Clubcard prices. [one of: paknsave, newworld]
- `query` (string, optional) — Part of the store name or address (case-insensitive).
- `region` (enum, optional) — Only stores on this island. [one of: NI, SI]
- `latitude` (number, optional) — With longitude: sort stores by straight-line distance from this point (distance_km).
- `longitude` (number, optional) — With latitude.
- `limit` (integer, optional, default 200) — How many stores to return (default all).

**Returns:** banner, total_stores, returned, stores[]{store_id, name, banner, region, address, latitude, longitude, distance_km, phone, click_and_collect, delivery, online_active, physical_store_code, hours{monday … sunday}}

**Example request body:**
```json
{
  "banner": "newworld",
  "query": "Auckland"
}
```

## At scale
- **Volume:** 5M+ requests a day, measured at 60 requests a second across the fleet with no
  central bottleneck. Per-key limits are raised for high-volume accounts; volume pricing on request.
- **Missing a source:** tell us a site we do not cover and it becomes an engine. A customer asked
  for bestprice.gr on 21 Sep 2026 and it was in the catalog on 22 Sep.
- **Support:** 2 minute median time from a question in the live chat to the first answer. Setup
  help included, no support tier to buy.
- **One key, one credit pool** across every API. No per-site plans, no separate subscriptions.

## More
- Try it live, no code: https://reefapi.com/playground?engine=paknsave
- Human docs page: https://reefapi.com/docs/paknsave
- Overview page: https://reefapi.com/paknsave-api
- Every ReefAPI API in one file (for your AI): https://reefapi.com/llms-full.txt