# Makro South Africa API — makro.co.za prices in rand, was-price and discount, More4Less multi-buys, stock, sellers, specifications, the full category tree with counts, batch price refresh, delivery per postal code and the Makro store directory

> Search Makro's online shop: price in rand, was-price, discount, stock, seller (Makro or a marketplace seller), brand, pack size, rating and image per product, with the site's total and page count. Filters: brand, price range, minimum discount, More4Less deals, sold by Makro, out-of-stock, and a category to search inside.
> ReefAPI engine `makro` · 8 endpoints · clean JSON, no scraping or browsers to manage.

## How to call
- **Endpoint:** `POST https://api.reefapi.com/makro/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.
- **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). Clients that add connectors by URL, such as ChatGPT and the Claude app, connect with OAuth 2.1 (the user pastes their key once on a ReefAPI page; discovery at `/.well-known/oauth-protected-resource/mcp`). Config files send the key as `Authorization: Bearer <key>`. `?key=<key>` in the URL also works as a last-resort fallback.

## Endpoints

### POST https://api.reefapi.com/makro/v1/search — 2 credits
Search Makro's online shop: price in rand, was-price, discount, stock, seller (Makro or a marketplace seller), brand, pack size, rating and image per product, with the site's total and page count. Filters: brand, price range, minimum discount, More4Less deals, sold by Makro, out-of-stock, and a category to search inside.

**Parameters:**
- `query` (string, required) — What to search for, as typed in the site's search box.
- `category_id` (string, optional) — Makro category id from `categories` / `subcategories` (e.g. 'eat' = Food Products, 'eat,zn0' = Milk) or a makro.co.za category URL containing sid=….
- `page` (integer, optional, default 1) — Page number, 1-50. The site's own page size is used (40 products, 24 in list-style categories such as TVs); Makro serves no page past 50, so one listing reaches at most 50 pages — walk bigger categories through `subcategories` or a price range.
- `sort` (enum, optional, default "relevance") — Order of the results, the site's own sort options. [one of: relevance, popularity, price_asc, price_desc, newest]
- `brand` (array, optional) — Only these brands, written as the `brand` field of a row or a `brands` facet (one or several, comma-separated).
- `price_min` (number, optional) — Lowest price in rand (inclusive).
- `price_max` (number, optional) — Highest price in rand (inclusive).
- `min_discount` (enum, optional) — Only products discounted at least this much against their was-price. [one of: 10, 20, 30, 40, 50]
- `more4less` (boolean, optional, default false) — Only products in Makro's More4Less promotion (multi-buy deals such as 'Buy any 3 at R 50.00' and markdowns).
- `sold_by_makro` (boolean, optional, default false) — Only products sold by Makro itself (leave out marketplace sellers).
- `include_out_of_stock` (boolean, optional, default false) — Also list out-of-stock products (the site hides them by default: Milk 141 → 170).
- `postal_code` (string, optional) — South African delivery postal code (4 digits) — the location Makro prices for. Most prices are national, but Western Cape codes (e.g. 8001 Cape Town) get their own price on soft drinks and some other products (measured). Default: Makro's own default location, 2157 Sandton.

**Returns:** query, category_id, sort, filters, postal_code, postal_code_defaulted, total, page, page_size, total_pages, reachable_pages, complete_walk_possible, returned, products[]{rank, product_id, item_id, listing_id, title, brand, pack_size, price, currency ('ZAR'), original_price, savings, discount_percent, price_per_unit, in_stock, availability, seller_id, sold_by_makro, rating, rating_count, review_count, key_specs[], category{super, sub, leaf}, image, images[], url}, subcategories[]{category_id, name, menu_product_count, url}, brands[]{name, count}

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

### POST https://api.reefapi.com/makro/v1/category — 2 credits
Every product of one Makro category, page by page, with the total and the page count so the whole category can be walked; also its subcategories with product counts (to walk a category bigger than the 50 pages the site serves). Same filters as search.

**Parameters:**
- `category_id` (string, required) — Makro category id from `categories` (e.g. 'eat,zn0' = Milk), 'all' for the whole shop, or a category URL with sid=….
- `page` (integer, optional, default 1) — Page number, 1-50. The site's own page size is used (40 products, 24 in list-style categories such as TVs); Makro serves no page past 50, so one listing reaches at most 50 pages — walk bigger categories through `subcategories` or a price range.
- `sort` (enum, optional, default "relevance") — Order of the results, the site's own sort options. [one of: relevance, popularity, price_asc, price_desc, newest]
- `brand` (array, optional) — Only these brands, written as the `brand` field of a row or a `brands` facet (one or several, comma-separated).
- `price_min` (number, optional) — Lowest price in rand (inclusive).
- `price_max` (number, optional) — Highest price in rand (inclusive).
- `min_discount` (enum, optional) — Only products discounted at least this much against their was-price. [one of: 10, 20, 30, 40, 50]
- `more4less` (boolean, optional, default false) — Only products in Makro's More4Less promotion (multi-buy deals such as 'Buy any 3 at R 50.00' and markdowns).
- `sold_by_makro` (boolean, optional, default false) — Only products sold by Makro itself (leave out marketplace sellers).
- `include_out_of_stock` (boolean, optional, default false) — Also list out-of-stock products (the site hides them by default: Milk 141 → 170).
- `postal_code` (string, optional) — South African delivery postal code (4 digits) — the location Makro prices for. Most prices are national, but Western Cape codes (e.g. 8001 Cape Town) get their own price on soft drinks and some other products (measured). Default: Makro's own default location, 2157 Sandton.

**Returns:** category_id, name, category_path[], sort, filters, postal_code, postal_code_defaulted, total, page, page_size, total_pages, reachable_pages, complete_walk_possible, returned, products[]{rank, product_id, item_id, listing_id, title, brand, pack_size, price, currency ('ZAR'), original_price, savings, discount_percent, price_per_unit, in_stock, availability, seller_id, sold_by_makro, rating, rating_count, review_count, key_specs[], category{super, sub, leaf}, image, images[], url}, subcategories[]{category_id, name, menu_product_count, url}, brands[]{name, count}

**Example request body:**
```json
{
  "category_id": "eat,zn0"
}
```

### POST https://api.reefapi.com/makro/v1/categories — 2 credits
Makro's category tree one level at a time: the top-level departments (43) or the subcategories of one category, each with its id and the product count the site shows. Walk down until a category fits in 50 pages, then page it with `category`.

**Parameters:**
- `category_id` (string, optional) — Category whose subcategories to list; leave out for the top level.

**Returns:** category_id, name, category_path[], product_count, total_pages, reachable_pages, subcategories[]{category_id, name, menu_product_count, url}

**Example request body:**
```json
{
  "category_id": "eat"
}
```

### POST https://api.reefapi.com/makro/v1/product — 2 credits
One Makro product in full: price, was-price, discount, every promotion with its multi-buy price and end date, stock, seller, brand, pack size, model number, highlights, all specifications, warranty, return policy, rating, category path, all images, delivery date and the nearest pickup store's availability.

**Parameters:**
- `product_id` (string, required) — The 16-character product_id a search row returns, or a makro.co.za product URL containing pid=….
- `postal_code` (string, optional) — South African delivery postal code (4 digits) — the location Makro prices for. Most prices are national, but Western Cape codes (e.g. 8001 Cape Town) get their own price on soft drinks and some other products (measured). Default: Makro's own default location, 2157 Sandton.

**Returns:** postal_code, postal_code_defaulted, product{product_id, item_id, listing_id, title, brand, pack_size, model_number, price, currency, original_price, savings, discount_percent, price_per_unit, savings_text, in_stock, availability, buyable, seller{id, name}, sold_by_makro, offers[]{offer_id, title, description, tags[], kind, quantity, deal_price, applied_on, ends, offer_url}, multi_buy{quantity, price, text, ends}, rating, rating_count, review_count, highlights[], variant_attributes{}, specifications[]{group, attributes[]{name, value}}, warranty, return_policy, delivery_days, category_path[]{name, category_id}, category, image, images[], url, delivery{postal_code, suburb, delivery, delivery_fee_note, pickup{store, address, postal_code, distance, hours, availability}}}

**Example request body:**
```json
{
  "product_id": "MLKHFXJTMV3AMYRY"
}
```

### POST https://api.reefapi.com/makro/v1/products — 3 credits
Price and stock for up to 100 Makro products in one call (one upstream request) — the cheap way to refresh a catalogue you already hold: price, was-price, discount, stock, seller, rating, image and URL per product_id; unknown ids are listed in not_found.

**Parameters:**
- `product_ids` (array, required) — 1-100 product ids (comma-separated or a list).
- `postal_code` (string, optional) — South African delivery postal code (4 digits) — the location Makro prices for. Most prices are national, but Western Cape codes (e.g. 8001 Cape Town) get their own price on soft drinks and some other products (measured). Default: Makro's own default location, 2157 Sandton.

**Returns:** requested, returned, not_found[], postal_code, postal_code_defaulted, products[]{product_id, item_id, listing_id, title, brand, pack_size, price, currency ('ZAR'), original_price, savings, discount_percent, price_per_unit, in_stock, availability, seller_id, sold_by_makro, rating, rating_count, review_count, key_specs[], category{super, sub, leaf}, image, images[], url}

**Example request body:**
```json
{
  "product_ids": "MLKHFXJTMV3AMYRY,DIRHCM4HF8TY9MGV"
}
```

### POST https://api.reefapi.com/makro/v1/offers — 1 credit
Every seller's offer for one Makro product (Makro and marketplace sellers): price, was-price, availability, delivery date, delivery charge and order cut-off for a postal code, payment modes, return policy.

**Parameters:**
- `product_id` (string, required) — The product_id (or a product URL with pid=…).
- `postal_code` (string, optional) — South African delivery postal code (4 digits) — the location Makro prices for. Most prices are national, but Western Cape codes (e.g. 8001 Cape Town) get their own price on soft drinks and some other products (measured). Default: Makro's own default location, 2157 Sandton.

**Returns:** product_id, title, brand, postal_code, city, seller_count, offers[]{listing_id, seller{id, name}, sold_by_makro, price, currency, original_price, discount_percent, available, buyable, listing_status, max_order_quantity, delivery_date, delivery_text, delivery_cutoff, delivery_charge, free_delivery, payment_modes[], return_policy, selected}

**Example request body:**
```json
{
  "product_id": "MLKHFXJTMV3AMYRY",
  "postal_code": "8001"
}
```

### POST https://api.reefapi.com/makro/v1/promotions — 2 credits
Products on a deal at Makro — discounted against their was-price (10-50% or more) or in the More4Less promotion — across the whole shop, inside a category, or matching a search.

**Parameters:**
- `query` (string, optional) — Deals whose product matches this search (optional).
- `category_id` (string, optional) — Makro category id from `categories` / `subcategories` (e.g. 'eat' = Food Products, 'eat,zn0' = Milk) or a makro.co.za category URL containing sid=….
- `deal_type` (enum, optional, default "discount") — Which deals: price discounts (default, at least min_discount) or the More4Less promotion. [one of: discount, more4less]
- `min_discount` (enum, optional, default "10") — With deal_type=discount: the minimum discount (default 10%). [one of: 10, 20, 30, 40, 50]
- `page` (integer, optional, default 1) — Page number, 1-50. The site's own page size is used (40 products, 24 in list-style categories such as TVs); Makro serves no page past 50, so one listing reaches at most 50 pages — walk bigger categories through `subcategories` or a price range.
- `sort` (enum, optional, default "relevance") — Order of the results, the site's own sort options. [one of: relevance, popularity, price_asc, price_desc, newest]
- `brand` (array, optional) — Only these brands, written as the `brand` field of a row or a `brands` facet (one or several, comma-separated).
- `price_min` (number, optional) — Lowest price in rand (inclusive).
- `price_max` (number, optional) — Highest price in rand (inclusive).
- `sold_by_makro` (boolean, optional, default false) — Only products sold by Makro itself (leave out marketplace sellers).
- `postal_code` (string, optional) — South African delivery postal code (4 digits) — the location Makro prices for. Most prices are national, but Western Cape codes (e.g. 8001 Cape Town) get their own price on soft drinks and some other products (measured). Default: Makro's own default location, 2157 Sandton.

**Returns:** query, category_id, deal_type, min_discount, note_discount, postal_code, postal_code_defaulted, total, page, page_size, total_pages, reachable_pages, complete_walk_possible, returned, products[]{rank, product_id, item_id, listing_id, title, brand, pack_size, price, currency ('ZAR'), original_price, savings, discount_percent, price_per_unit, in_stock, availability, seller_id, sold_by_makro, rating, rating_count, review_count, key_specs[], category{super, sub, leaf}, image, images[], url}, subcategories[]{category_id, name, menu_product_count, url}, brands[]{name, count} (deal_type=discount rows also carry discount_visible)

**Example request body:**
```json
{
  "category_id": "eat"
}
```

### POST https://api.reefapi.com/makro/v1/stores — 1 credit
Makro stores: the three nearest to an address, town or postal code (name, address, province, distance, trading hours, store id), or the whole store directory with all=true.

**Parameters:**
- `address` (string, optional) — A town, suburb or address in South Africa (postal codes work in the metros; a town name is safer).
- `all` (boolean, optional, default false) — Return every Makro store (the directory, swept from the site's own store lookup across the country).

**Returns:** address, returned, stores[]{store_id, name, store_type, address, postal_code, province, distance_km, hours, pickup}

**Example request body:**
```json
{
  "address": "Cape Town"
}
```

## 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=makro
- Human docs page: https://reefapi.com/docs/makro
- Overview page: https://reefapi.com/makro-api
- Every ReefAPI API in one file (for your AI): https://reefapi.com/llms-full.txt
