Flipp Grocery Deals Scraper

Scrape real, store-level weekly-ad prices near any US or Canadian postal code, sourced from Flipp — 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

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

Example: search with digital coupons and price range

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

Example: browse all active flyers near a postal code

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

Example: list every item in a specific flyer

{
  "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.