Flipp APIflipp.com ↗
Search grocery deals and weekly circulars from retailers near any US ZIP code. Access sale prices, flyer items, and validity dates via 3 endpoints.
What is the Flipp API?
The Flipp API gives developers access to grocery deals and weekly ad circulars from major US retailers across 3 endpoints. Use search_deals to find matching sale items by keyword and ZIP code, get_weekly_ads to list available flyers near a location, and get_flyer_items to retrieve every sale item in a specific circular. Each response includes item names, current and original prices, merchant names, and promotion validity dates.
curl -X GET 'https://api.parse.bot/scraper/a496e089-6377-4719-bec7-21aa74d15185/search_deals?query=chicken&postal_code=95054' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace flipp-com-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""Walkthrough: Flipp SDK — bounded, re-runnable; every call capped."""
from parse_apis.flipp_com_api import Flipp, FlyerNotFound
client = Flipp()
# Search for grocery deals by keyword near a zip code.
for deal in client.deals.search(query="chicken", postal_code="95054", limit=3):
print(deal.name, deal.current_price, deal.merchant_name)
# List weekly ads for a specific retailer.
flyer = client.flyers.list(postal_code="95054", merchant_name="Safeway", limit=1).first()
if flyer:
print(flyer.name, flyer.merchant, flyer.valid_from, flyer.valid_to)
# Browse the flyer's items.
if flyer:
try:
for item in flyer.items.list(limit=3):
print(item.name, item.price, item.brand)
except FlyerNotFound as e:
print("flyer gone:", e.flyer_id)
print("exercised: deals.search, flyers.list, flyer.items.list")
Full-text search for grocery deals and sale items from weekly circulars. Returns flyer items matching the query from all retailers near the given postal code, including item name, current and original price, merchant, and validity dates.
| Param | Type | Description |
|---|---|---|
| queryrequired | string | Search keyword for deals (e.g. chicken, milk, cereal). |
| postal_coderequired | string | 5-digit US ZIP code to search deals near. |
{
"type": "object",
"fields": {
"items": "array of deal items from weekly circulars",
"query": "the search query echoed back",
"total": "integer count of items returned",
"postal_code": "the postal code echoed back"
},
"sample": {
"data": {
"items": [
{
"id": 1027077541,
"name": "Tyson® Bagged Chicken",
"flyer_id": 8034374,
"valid_to": "2026-07-26T03:59:59+00:00",
"image_url": "https://f.wishabi.net/page_items/427714164/1784257359/extra_large.jpg",
"sale_story": null,
"valid_from": "2026-07-19T07:00:00+00:00",
"category_l1": "Food, Beverages & Tobacco",
"category_l2": "Food Items",
"merchant_id": 2063,
"current_price": 6.25,
"merchant_name": "Dollar General",
"original_price": 6.75,
"pre_price_text": "SALE",
"post_price_text": null
}
],
"query": "chicken",
"total": 57,
"postal_code": "95054"
},
"status": "success"
}
}About the Flipp API
What the API Returns
The Flipp API surfaces deal data from weekly retail circulars at three levels of granularity. search_deals accepts a query string and a postal_code and returns a ranked array of matching items drawn from all retailer flyers near that location. Each item includes the deal name, current price, original price, merchant, and the start/end dates the promotion is valid. The total field tells you how many items matched the query.
Browsing Flyers by Location or Retailer
get_weekly_ads lists all active flyers available near a given postal_code. An optional merchant_name parameter (case-insensitive, partial matches accepted) narrows results to a specific chain — for example, passing Safeway returns only Safeway circulars. Each flyer object in the response includes a flyer_id that serves as the key input to get_flyer_items. The merchant_filter field in the response echoes back the filter you applied, or null if none was used.
Drilling Into a Single Circular
get_flyer_items takes a flyer_id from get_weekly_ads and returns the full contents of that retailer's weekly ad. The items array includes all sale entries in the circular — names, brands, prices, and validity dates — along with a total count. This makes it straightforward to index a complete circular or compare prices across two flyers from the same retailer in different weeks.
The Flipp API is a managed, monitored endpoint for flipp.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when flipp.com changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official flipp.com API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Build a grocery price comparison tool that queries
search_dealsfor a product across multiple ZIP codes - Alert users when a specific item like 'chicken breast' appears on sale near their postal code
- Aggregate weekly ad start dates from
get_weekly_adsto notify users when new circulars drop - Index a full retailer circular using
get_flyer_itemsto power a local deal search feature - Track price history for common grocery items by recording
current_priceandoriginal_priceover time - Filter
get_weekly_adsbymerchant_nameto build a retailer-specific deal digest - Surface the best deals near a given ZIP code for a coupon or savings app
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does Flipp have an official developer API?+
What does `search_deals` return compared to `get_flyer_items`?+
search_deals returns items matching a keyword from all retailer flyers near a ZIP code — useful for cross-retailer price checks on a specific product. get_flyer_items returns every item in one specific flyer identified by a flyer_id, which you first obtain from get_weekly_ads. The two endpoints complement each other: use search_deals for targeted lookups and get_flyer_items to browse a complete circular.Does the API cover Canadian postal codes or only US ZIP codes?+
Does the API return coupon codes or digital clip-to-card promotions?+
How current is the deal data, and does it paginate?+
total reflects the full result count in that one call.