# Flipp Grocery Deals Scraper (`crawlerbros/flipp-grocery-deals-scraper`) Actor

Scrape real store-level weekly-ad prices near any US or Canadian postal code - Kroger, Publix, ALDI, Walmart, Target, Costco, CVS, Walgreens and dozens more retailers. Search by product keyword or browse all active flyers for an area. No login, no API key.

- **URL**: https://apify.com/crawlerbros/flipp-grocery-deals-scraper.md
- **Developed by:** [Crawler Bros](https://apify.com/crawlerbros) (community)
- **Categories:** Automation, E-commerce, Integrations
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $3.00 / 1,000 results

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## Flipp Grocery Deals Scraper

Scrape real, store-level weekly-ad prices near any US or Canadian postal code, sourced from [Flipp](https://flipp.com) — the platform that digitizes weekly circulars for **Kroger, Publix, ALDI, Walmart, Target, Costco, CVS, Walgreens, Meijer, Sam's Club** and dozens of other US/Canada retailers. Search by product keyword to get current prices across every nearby store, or browse all active flyers for an area. No login, no API key, no cookies.

### What this actor does

- **Four modes:** `search` (product keyword → priced items across nearby stores), `flyers` (browse every active weekly-ad flyer near a postal code), `flyerItems` (list every single item printed inside one specific flyer, by flyer ID), and `merchants` (Flipp's full ~2,500-retailer directory, with merchant IDs/names for use in other modes)
- **Two item types in search mode:** weekly-ad flyer items (in-store circular pricing, with valid date ranges) and online/e-commerce items (marketplace pricing) — filter to either or both
- **Filters:** merchant name, category, min/max price, item type
- **Sort (mode=search):** relevance, price low-to-high, price high-to-low
- **Digital coupons (mode=search):** optionally emit real manufacturer/store coupon offers (savings text, disclaimer, matched product) surfaced alongside a search
- **Real store-level pricing:** `currentPrice`, `originalPrice`, sale copy, valid-from/to dates
- **Merchant branding:** `merchantLogoUrl` on every item/flyer record
- **Empty fields are omitted** — you'll never see `null` or `"N/A"` in the output

### Output per record (search mode)

- `itemId`, `name`
- `currentPrice`, `originalPrice` — USD/CAD
- `priceQualifier` — e.g. "with digital coupon", "/EA"
- `saleStory` — promotional copy, when present
- `merchantName` — e.g. `Kroger`, `Publix`, `ALDI`
- `merchantId` — Flipp's numeric retailer ID (cross-reference with `merchants` mode)
- `merchantLogoUrl`
- `category`, `subcategory`
- `imageUrl` — product/circular clipping image
- `validFrom`, `validTo` — ISO dates (flyer items only)
- `flyerId`, `averageRating`, `totalReviews` — when available
- `sourceUrl` — the Flipp flyer/page this price came from
- `itemType` — `flyer` or `ecom`
- `isRelatedItem` — `true` only for cross-sell/related suggestions when `includeRelatedItems` is on
- `recordType: "product"` (`"relatedItem"` for related suggestions), `scrapedAt`

### Output per record (search mode coupons, when `includeCoupons` is on)

- `couponId`, `savingsText` — e.g. "$2.00 off 1"
- `disclaimerText` — the coupon's legal/redemption terms
- `productNames[]` — matched product(s)/brand(s)
- `requiredQuantity` — units required to redeem, when stated
- `recordType: "coupon"`, `scrapedAt`

### Output per record (flyers mode)

- `flyerId`, `merchantName`, `merchantId`, `name`
- `validFrom`, `validTo`
- `categories[]`
- `thumbnailUrl`, `merchantLogoUrl`
- `postalCode`, `sourceUrl`
- `recordType: "flyer"`, `scrapedAt`

### Output per record (flyerItems mode)

- `itemId`, `flyerId`, `name`, `brand`
- `price` — USD/CAD
- `discountPercent` — when the flyer marks a % off
- `validFrom`, `validTo`
- `imageUrl` — the cut-out product image from the scanned flyer page
- `merchantPageUrl` — the retailer's own product/landing page, when the flyer links to one
- `sourceUrl` — the Flipp flyer page
- `recordType: "flyerItem"`, `scrapedAt`

### Output per record (merchants mode)

- `merchantId`, `merchantName`, `nameIdentifier`
- `usBased` — whether the retailer is US-based
- `sourceUrl` — the retailer's Flipp storefront page
- `recordType: "merchant"`, `scrapedAt`

### Input

| Field | Type | Default | Description |
|---|---|---|---|
| `mode` | string | `search` | `search` / `flyers` / `flyerItems` / `merchants` |
| `postalCode` | string | `45202` | US ZIP or Canadian postal code (required for `search`/`flyers`; unused for `flyerItems`) |
| `query` | string | `milk` | Product keyword (mode=search) |
| `itemType` | string | `all` | `all` / `flyer` / `ecom` (mode=search) |
| `sortBy` | string | `relevancy` | `relevancy` / `price_low_to_high` / `price_high_to_low` (mode=search) |
| `flyerIds` | array | `[]` | Numeric flyer IDs to list every item from (mode=flyerItems, required) |
| `merchantName` | string | – | Keep only this merchant (substring match) |
| `category` | string | – | Keep only this category (substring match) |
| `minPrice` / `maxPrice` | number | – | Price range filter |
| `includeRelatedItems` | boolean | `false` | Also emit Flipp's cross-sell "related items" suggestions, when the query surfaces any (mode=search) |
| `includeCoupons` | boolean | `false` | Also emit real digital-coupon offers surfaced alongside the search, when any exist (mode=search) |
| `maxItems` | integer | `40` | Hard cap on emitted records |

#### Example: search for a product near a US zip code

```json
{
  "mode": "search",
  "postalCode": "45202",
  "query": "chicken breast",
  "itemType": "flyer",
  "sortBy": "price_low_to_high"
}
```

#### Example: search with digital coupons and price range

```json
{
  "mode": "search",
  "postalCode": "K1A 0B1",
  "query": "paper towels",
  "minPrice": 2,
  "maxPrice": 15,
  "includeCoupons": true
}
```

#### Example: browse all active flyers near a postal code

```json
{
  "mode": "flyers",
  "postalCode": "90210",
  "merchantName": "Costco"
}
```

#### Example: list every item in a specific flyer

```json
{
  "mode": "flyerItems",
  "flyerIds": ["8041414"]
}
```

### Use cases

- Track Kroger/Publix/ALDI prices for a shopping list across a zip code
- Compare weekly-ad pricing for the same product across multiple retailers
- Monitor grocery price trends over time by re-running the actor on a schedule
- Build a "what's on sale near me" digest for a specific postal code
- Coupon/promo teams tracking manufacturer digital-coupon offers by region
- Retail analysts benchmarking a merchant's pricing footprint across zip codes

### FAQs

**Does this require login or cookies?**
No. Flipp's price-search API is public and unauthenticated.

**Why do I get different results for the same query in different zip codes?**
Flyer pricing is store-specific — the same product can be priced differently (or not carried at all) depending on which stores' circulars are active near that postal code.

**Does this cover Kroger specifically?**
Yes — Kroger's weekly-ad circular is one of the retailers indexed by Flipp in most US zip codes where Kroger operates (it's a widely available banner via Flipp's digital-circular network). Availability depends on postal code.

**Is proxy required?**
No. This is a plain public JSON API call — no residential proxy needed.

**Is this affiliated with Flipp or the retailers listed?**
No. This is a third-party actor built against Flipp's public price-search API; it is not affiliated with Flipp, Kroger, Publix, ALDI, Walmart, or any other listed retailer.

**How do I find a flyer ID for `flyerItems` mode?**
Run `mode=search` or `mode=flyers` for your postal code first — every result includes a `flyerId` field you can feed into `flyerItems`. Flyer IDs are also visible in `flipp.com/en-us/flyer/<id>` URLs.

**Why are `averageRating` and `totalReviews` missing on some items?**
Those fields only exist for online/e-commerce items that have received customer reviews; in-store weekly-ad flyer items don't carry them.

**Can I get historical pricing, not just current prices?**
No. Flipp only exposes the currently active weekly circular; re-run the actor on a schedule to build your own price-history dataset over time.

### Limitations

- Coverage is store/region dependent: a given retailer's flyer only appears for postal codes where that retailer operates.
- `averageRating` / `totalReviews` are only present for e-commerce items that have received reviews.
- Flyer item prices reflect the currently active weekly circular; historical pricing is not available.

# Actor input Schema

## `mode` (type: `string`):

What to fetch.

## `postalCode` (type: `string`):

A US ZIP code (e.g. `45202`) or Canadian postal code (e.g. `K1A 0B1`). Determines which stores' flyers/prices are searched. Not used for mode=flyerItems or mode=merchants.

## `query` (type: `string`):

Product keyword, e.g. `milk`, `chicken breast`, `paper towels`.

## `itemType` (type: `string`):

Filter to weekly-ad flyer items (in-store circular pricing), online/e-commerce items, or both.

## `sortBy` (type: `string`):

Order search results before filtering.

## `merchantName` (type: `string`):

Only keep results from a merchant whose name contains this text, e.g. `Kroger`, `Publix`, `ALDI`, `Walmart`, `Costco`, `CVS`. Also applies in mode=merchants.

## `category` (type: `string`):

Only keep results whose category/subcategory contains this text, e.g. `Beverages`, `Meat`, `Dairy`.

## `flyerIds` (type: `array`):

Numeric flyer IDs to list every item from, e.g. `8041414`. Get IDs from the `flyerId` field of `search`/`flyers` mode output, or from a flyer URL like `flipp.com/en-us/flyer/8041414`.

## `minPrice` (type: `number`):

Drop items priced below this (USD/CAD).

## `maxPrice` (type: `number`):

Drop items priced above this (USD/CAD).

## `includeRelatedItems` (type: `boolean`):

Also emit Flipp's 'related items' (cross-sell/adjacent product suggestions returned alongside some search results, e.g. searching `iphone` surfaces related phone-plan or accessory deals). Off by default since most queries return none.

## `includeCoupons` (type: `boolean`):

Also emit real digital-coupon offers (savings text, disclaimer, matched product) surfaced alongside search results for that postal code, e.g. `$2.00 off Tyson`. Off by default since not every query surfaces coupons.

## `maxItems` (type: `integer`):

Hard cap on emitted records.

## Actor input object example

```json
{
  "mode": "search",
  "postalCode": "45202",
  "query": "milk",
  "itemType": "all",
  "sortBy": "relevancy",
  "flyerIds": [],
  "includeRelatedItems": false,
  "includeCoupons": false,
  "maxItems": 40
}
```

# Actor output Schema

## `deals` (type: `string`):

Dataset containing all scraped products/prices or flyers.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "mode": "search",
    "postalCode": "45202",
    "query": "milk",
    "itemType": "all",
    "sortBy": "relevancy",
    "flyerIds": [],
    "includeRelatedItems": false,
    "includeCoupons": false,
    "maxItems": 40
};

// Run the Actor and wait for it to finish
const run = await client.actor("crawlerbros/flipp-grocery-deals-scraper").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "mode": "search",
    "postalCode": "45202",
    "query": "milk",
    "itemType": "all",
    "sortBy": "relevancy",
    "flyerIds": [],
    "includeRelatedItems": False,
    "includeCoupons": False,
    "maxItems": 40,
}

# Run the Actor and wait for it to finish
run = client.actor("crawlerbros/flipp-grocery-deals-scraper").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"])
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "mode": "search",
  "postalCode": "45202",
  "query": "milk",
  "itemType": "all",
  "sortBy": "relevancy",
  "flyerIds": [],
  "includeRelatedItems": false,
  "includeCoupons": false,
  "maxItems": 40
}' |
apify call crawlerbros/flipp-grocery-deals-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=crawlerbros/flipp-grocery-deals-scraper",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/MJLMMQaFGbfQjZeDO/builds/kepyKEnzegM7rhe2e/openapi.json