Instacart API & Scraper
The Instacart API turns instacart.com and instacart.ca into clean JSON for the postal code you choose, in four actions: search, product/detail, retailers and suggest.
🤖 Using an AI assistant? Copy this link into ChatGPT / Claude / Cursor — it reads every endpoint and parameter instantly and tells you if this API fits your use case.
product/detail returns one product's current price at every retailer selling it at that postal code in a single call, lowest first - Häagen-Dazs Pistachio at 90210 came back with 112 retailer prices from $3.59 to $14.99 on 2026-09-15 - plus the product record: name, brand, size, category, breadcrumb, description, ingredients, warnings, images and rating. retailers lists every store Instacart serves there (276 retailers at 90210, 87 at M5V 3L9 Toronto) with delivery and pickup. search returns products grouped by retailer, each priced at that retailer's store: regular price, was-price and discount, the loyalty-card price kept apart, promotions such as Buy 1, get 1 free, unit price, weight-estimated package prices and stock level including Likely out of stock. Prices come back in USD for the US and CAD for Canada. Verification on 2026-09-15: 22 of 22 searches across 16 postal codes in both countries and 44 of 44 product reads succeeded, 42 of 42 controlled cases passed, 7 of 7 products matched an independent read of the source, and search prices agreed with the per-retailer prices on 40 of 40 products. No Instacart account needed - one ReefAPI key and the standard { ok, data, meta, error } envelope.
Which Instacart price is which - loyalty, sale, per-lb and estimated packages
Instacart shows a product's price several ways, and a tracker that stores one number mixes them. The API names each case. Measured on 2026-09-15.
| Instacart row | price | What else comes back | How to read it |
|---|---|---|---|
| Häagen-Dazs Pistachio Ice Cream at Walmart, 90210 | 3.87 USD | original_price 4.58, discount_percent 16 | On sale: the store price and the was-price together |
| A Ralphs row with a loyalty-card price | 3.29 USD | loyalty_price 2.79, loyalty_label With loyalty card | price is the regular price; the card price is a separate field |
| Häagen-Dazs Pistachio at Ralphs, 90210 | 6.99 USD | promotions: Buy 1, get 1 free, deal_terms Add 2 to qualify for deal | The offer is never subtracted from price |
| Simple Truth Natural Chicken Breasts at Kroger, 77002 | 13.48 USD | price_is_estimate true, unit_price_text $5.99 / lb, About 2.25 lb / package | Sold by weight: price is the estimated package |
| The same chicken in product/detail offers | 5.99 USD | offer_price_unit lb | Retailer comparison for weighed products is per lb |
Instacart's retailer prices are the prices the retailer sets for Instacart orders; Instacart says each retailer follows its own pricing policy, so they can differ from the shelf price in the physical store. Stock level Likely out of stock is returned even though Instacart still marks the item available - 5 of 1,396 search rows on 2026-09-15.
Real request and response JSON
Captured from the indexed primary action, search, on .
{
"method": "POST",
"url": "https://api.reefapi.com/instacart/v1/search",
"headers": {
"x-api-key": "$REEF_KEY",
"content-type": "application/json"
},
"body": {
"query": "milk",
"postal_code": "90210"
}
}{
"ok": true,
"meta": {
"api": "instacart",
"endpoint": "search",
"mode": "live",
"latency_ms": 3987.1,
"record_count": 49,
"bytes": 523834,
"cache_hit": false,
"pagination": {
"page": 1,
"has_more": true,
"page_size": 5,
"total": 151
},
"upstream_requests": 15
},
"data": {
"__trimmed": "response capped for page display"
}
}What the Instacart API does
| Action | Description | Concrete use case | Key params |
|---|---|---|---|
| search | Search Instacart by keyword at a postal code. Products come back grouped by retailer, each priced at that retailer's store serving the postal code: regular price, was-price and discount, loyalty-card price, promotions such as Buy 1 get 1, unit price, weight-estimated package price, stock level including 'Likely out of stock', dietary badges and Instacart's best-seller badge. Optionally one retailer only. | Pricing teams call search to search Instacart by keyword at a postal code. | query, postal_code, country, retailer, max_retailers, ... |
| product/detail | One Instacart product: name, brand, size, category and breadcrumb, description, ingredients, directions, warnings, every image, rating and rating count — and, with a postal code, its current price at every retailer selling it there (lowest first, with was-prices). Add a retailer for that store's full item record: stock level, unit price, loyalty price and promotions. | Marketplace operators call product/detail to get one Instacart product. | product_id, postal_code, country, retailer, max_rotations |
| retailers | The retailers Instacart serves at a postal code — supermarkets, warehouse clubs, pharmacies, liquor, pet and specialty stores — with their slug and id for search and product/detail, retailer type, categories, logo, and whether they deliver, offer pickup, or both. | Catalog enrichment teams call retailers to get the retailers Instacart serves at a postal code. | postal_code, country, service_type, category, max_rotations |
| suggest | Instacart search-box suggestions for a partial query at a postal code. | Retail analysts call suggest to get instacart search-box suggestions for a partial query at a postal code.. | query, postal_code, country, max_rotations |
Call search from your stack
curl -X POST https://api.reefapi.com/instacart/v1/search \
-H "x-api-key: $REEF_KEY" \
-H "content-type: application/json" \
-d '{"query":"milk","postal_code":"90210"}'import requests
r = requests.post(
"https://api.reefapi.com/instacart/v1/search",
headers={"x-api-key": REEF_KEY},
json={
"query": "milk",
"postal_code": "90210"
},
)
print(r.json()["data"])const res = await fetch("https://api.reefapi.com/instacart/v1/search", {
method: "POST",
headers: {
"x-api-key": process.env.REEF_KEY,
"content-type": "application/json",
},
body: JSON.stringify({
"query": "milk",
"postal_code": "90210"
}),
});
const { ok, data, meta, error } = await res.json();Ask your MCP-connected assistant: call reefapi.instacart.search with {"query":"milk","postal_code":"90210"}.Who uses this API and why
- Grocery price-comparison apps show the cheapest retailer for a product at the shopper's postal code with one product/detail call.
- CPG brands monitor shelf price, sale price, loyalty price and promotions for their products across every retailer on Instacart in a market.
- Retail analysts track Buy 1, get 1 free and spend-and-save promotions by retailer and postal code, with per-lb prices kept apart from package prices.
- Delivery and logistics teams map which retailers serve which US ZIP codes and Canadian postal codes, with delivery and pickup.
Questions developers ask before integrating
How do I compare one product's price across retailers?
Call product/detail with the product_id and a postal_code. offers lists every retailer selling it there, lowest price first, each with price, was-price and discount; lowest_price and highest_price summarise it. A price far above the rest is checked against that store's own item: a store selling a case instead of a single item is marked comparable false with pack_count and price_each and left out of the range - Jif Creamy Peanut Butter 16 oz at 60614 ran $2.49 to $6.49, with a 12-jar case at $36.99 ($3.08 a jar) flagged. Häagen-Dazs Pistachio Ice Cream at 90210 on 2026-09-15: 112 retailer prices from $3.59 to $14.99, Walmart $3.87 down from $4.58. When Instacart's own comparison leaves a store out, the API prices it from that store's product listing, so the number matches what search shows for that store (source store_item). A retailer offering the same price for delivery and pickup appears once, with both service types.
Why are some offer prices per pound?
For products Instacart sells by weight, every retailer's offer is the price per pound, not the price of a package. The API says so in offer_price_unit (lb), so the list is still like for like. Search rows for the same product give the estimated package price with the per-lb unit price next to it: Simple Truth chicken breasts at Kroger 77002 read $13.48 for about 2.25 lb at $5.99 / lb, and the Kroger offer read $5.99.
Which postal codes and countries work?
Any 5-digit US ZIP with country us, and any Canadian postal code with country ca (M5V 3L9 or M5V3L9). Prices and stores are for that postal code, whichever you pick: the verification run used 13 US and 3 Canadian postal codes. A postal code Instacart does not serve returns NOT_FOUND; a malformed one, or a Canadian code with country us, returns INVALID_PARAM.
What does search return?
Products grouped by retailer, each retailer priced at its store serving the postal code. Retailers come in a fixed order (by Instacart retailer id) so that page 2 never repeats or skips a retailer from page 1 - Instacart ranks retailers differently for different visitors. By default 5 retailers and 10 products each; max_retailers goes to 20 and per_retailer to 40, which is the most Instacart returns per retailer for one query. page moves to the next retailers - milk at 90210 matched 151 retailers. retailer limits it to one store, by the slug or id retailers returns.
What happens with a query that matches nothing?
Instacart fills no-match searches with unrelated products and does not flag them. The API drops rows that share no word with your query and counts them in unmatched_dropped: blorptangzik returned 0 rows with 10 unrelated books dropped. Instacart's own spelling correction is kept - choclate returned 41 chocolate rows. include_unmatched=true returns every row.
Where do ratings come from?
From the rating Instacart shows on the product page, returned on a 0 to 5 scale with the rating count and the star distribution; no ratings means null. Ratings on Instacart can be syndicated from brand websites, and on some products they describe a different item from the same brand family - Häagen-Dazs Pistachio shows 4.15 from 1,097 ratings that come from a cosmetics brand. The API returns what Instacart publishes and does not offer review text.
What does Instacart NOT publish?
No stock counts, only a stock level and label. No delivery fees, service fees or delivery windows - those need an address and a cart. No in-store shelf price. Search returns at most 40 products per retailer for one query. Description and ingredients are published for branded goods: ingredients were filled on 30 of 44 sampled products and description on 18.
What is the Instacart API?
Instacart API is a ReefAPI endpoint group for one grocery product's price at every us and canadian retailer serving a postal code. It returns live JSON through POST requests under /instacart/v1.
Is the Instacart API free to try?
Yes. ReefAPI starts with 1,000 free credits, no card required. Instacart calls use the same shared credit balance as every other ReefAPI engine.
Do I need an Instacart login or account?
No login to Instacart is needed for the API response. You call ReefAPI with your x-api-key header, and the playground can run live examples before you create a production key.
How fresh is the Instacart data?
The page example is captured from a live search call, and production requests fetch live data through ReefAPI rather than a static sample.
How many credits does the Instacart API use?
Instacart actions currently cost 1-2 credits per successful call. Failed or blocked calls are free, and all APIs draw from one credit pool.
Can I call Instacart from an AI assistant or MCP client?
Yes. Connect ReefAPI once through MCP and your assistant can call instacart actions with the same key, credit pool and JSON envelope used by normal REST requests.
Is the Instacart API an Instacart scraper?
It is the managed alternative to a DIY Instacart scraper. Instead of building and maintaining your own scraper — proxies, headless browsers, captcha and constant breakage — you call one ReefAPI endpoint and get the same one grocery product's price at every us and canadian retailer serving a postal code back as clean JSON.