Costco prices as JSON, with every instant saving split into its parts
The Costco API turns costco.com and costco.ca into clean JSON in four actions: search, product/detail, category and search/suggest.
4 active endpoints. Every call is 1 credit.
- POST/costco/v1/search
- POST/costco/v1/product/detail
- POST/costco/v1/category
- POST/costco/v1/search/suggest
What Costco endpoints does ReefAPI ship?
4 live read endpoints. Read-only data API: no writes, no account actions, no dashboard access on the target site.
Costco API
3 of 4 endpoints, ready to run
Costco products for a keyword: the price after instant savings, the regular price and saving, the savings text and dates, member-only and price-in-cart flags, rating, availability and badges.
{ "ok": true, "meta": { "api": "costco", "endpoint": "search", "mode": "live", "latency_ms": 1948.4, "record_count": 24, "cache_hit": false }, "data": { "results": [ { "item_number": "1660437", "product_id": "100978861", "title": "Folgers Classic Roast Ground Coffee, Medium, 43.5 oz", "brand": "Folgers", "model": null, "gtin": "025500304212", "url": "https://www.costco.com/folgers-classic-roast-ground-coffee%2c-medium%2c-43.5-oz.product.100978861.html", "image": "https://gdx-assets.costco.com/adobe/assets/urn:aaid:aem:c4677644-3eea-44e8-8e0c-1c58499a126b/as/1660437-847__1.avif", "price": 22.99, "regular_price": null, "instant_savings": null, "savings_text": null, "price_valid_through": null, "marketing_statement": null, "price_range": null, "currency": "USD", "member_only": false, "price_in_cart_only": false, "price_display": "shown", "rating": 4.72, "review_count": 1117, "rating_scale": 5, "availability": "in_stock", "delivery_status": "in_stock", "programs": [ "3rdPartyDelivery", "2DayDelivery", "GoogleGrocery" ], "online_only": false, "warehouse_only": false, "costco_direct": false, "badges": [], "has_variants": false, "max_order_quantity": null, "fsa_eligible": false, "category_paths": [ "/grocery-household.html", "/coffee-sweeteners.html", "/ground-coffee.html" ] }, { "item_number": "1726089", "product_id": "4000232205", "title": "Kirkland Signature House Blend Whole Bean Coffee, Medium Roast, 2.5 lbs", "brand": "Kirkland Signature", "model": null, "gtin": "196633773852", "url": "https://www.costco.com/kirkland-signature-house-blend-whole-bean-coffee%2c-medium-roast%2c-2.5-lbs.product.4000232205.html", "image": "https://gdx-assets.costco.com/adobe/assets/urn:aaid:aem:552b8256-b1bc-4ac3-8b31-02d861fd0a83/as/1726089-847__1.avif", "price": 21.49, "regular_price": null, "instant_savings": null, "savings_text": null, "price_valid_through": null, "marketing_statement": null, "price_range": null, "currency": "USD", "member_only": false, "price_in_cart_only": false, "price_display": "shown", "rating": 4.17, "review_count": 743, "rating_scale": 5, "availability": "in_stock", "delivery_status": "in_stock", "programs": [ "3rdPartyDelivery", "2DayDelivery", "GoogleGrocery" ], "online_only": false, "warehouse_only": false, "costco_direct": false, "badges": [], "has_variants": false, "max_order_quantity": null, "fsa_eligible": false, "category_paths": [ "/whole-bean-coffee.html", "/grocery-household.html", "/coffee-sweeteners.html" ] }, { "item_number": "756053", "product_id": "100449422", "title": "Kirkland Signature Medium Roast Coffee, 40 oz.", "brand": "Kirkland Signature", "model": null, "gtin": "196633773845", "url": "https://www.costco.com/kirkland-signature-medium-roast-coffee%2c-40-oz..product.100449422.html", "image": "https://gdx-assets.costco.com/adobe/assets/urn:aaid:aem:09896d80-013f-4fe0-9c31-472a652ed8c9/as/100449422-847__1.avif", "price": 21.99, "regular_price": null, "instant_savings": null, "savings_text": null, "price_valid_through": null, "marketing_statement": null, "price_range": null, "currency": "USD", "member_only": false, "price_in_cart_only": false, "price_display": "shown", "rating": 4.74, "review_count": 668, "rating_scale": 5, "availability": "in_stock", "delivery_status": "in_stock", "programs": [ "3rdPartyDelivery", "2DayDelivery", "GoogleGrocery" ], "online_only": false, "warehouse_only": false, "costco_direct": false, "badges": [], "has_variants": false, "max_order_quantity": null, "fsa_eligible": false, "category_paths": [ "/kirkland-signature-groceries.html", "/grocery-household.html", "/coffee-sweeteners.html" ] } ], "count": 24, "total_results": 321, "page": 1, "page_size": 24, "duplicates_dropped": 0, "fallback_results_dropped": 0, "sponsored_dropped": 0, "filters_available": { "brands": [ { "value": "4 Cats & Dogs", "count": 1 }, { "value": "AB Outdoor Living", "count": 1 }, { "value": "ACP Ideas", "count": 3 } ], "price_ranges": [ { "value": "$0 to $25", "count": 87 }, { "value": "$25 to $50", "count": 86 }, { "value": "$50 to $100", "count": 35 } ], "ratings": [ { "value": "4 & Up", "count": 288 }, { "value": "3 & Up", "count": 309 }, { "value": "2 & Up", "count": 309 } ], "categories": [ { "value": "Appliances", "count": 31 }, { "value": "Clothing, Luggage & Handbags", "count": 1 }, { "value": "Floral & Gift Baskets", "count": 6 } ] }, "has_more": true, "query": "coffee", "matched_query": null, "redirected_to": null, "redirect_url": null, "sort_applied": "relevance", "country": "us", "language": "en", "currency": "USD" } }
How the Costco API works
Costco is a normal ReefAPI surface — the same four rules that hold for every other engine on the key.
No OAuth app, no request signing, no per-site account. One key covers all 252 engines.
Every route is a POST with a JSON body. Parameters are validated against the published schema before anything is charged.
Credits, not seats. Failed and blocked calls are never charged, and cache hits cost nothing.
One envelope everywhere. meta carries latency_ms, record_count and the endpoint that answered.
Track Costco's instant savings with the price members pay and the dates they end
Costco's savings rotate every few weeks and exist only as two prices and a line of text. Two calls give a list you can store and compare week to week.
{"query": "instant savings"}Products on a saving, each with price, regular_price, instant_savings and savings_text. On 2026-09-15, 15 of 24 rows carried a regular price.
{"item_number": "1919326"}27.39 USD instead of 32.99 USD, a 5.60 saving valid from 2026-08-24 to 2026-09-20, rating 4.78 from 2 160 reviews, the GTIN and the category pages.
A savings list where every item carries the price a member pays, the regular price, the saving and its end date - in the US or Canada, for one credit per call.
curl -X POST https://api.reefapi.com/costco/v1/search \
-H "x-api-key: $REEF_KEY" \
-H "content-type: application/json" \
-d '{"query":"coffee"}'{
"ok": true,
"data": { … },
"meta": {
"api": "costco",
"endpoint": "search",
"mode": "live",
"latency_ms": …,
"record_count": …
},
"error": null
}Costco shows a saving as two prices and a line of text - the API returns each part in its own field
Costco's instant savings are not a separate discount number: the saving is the gap between two prices, and its wording and dates are text. The API splits them. Values measured on 2026-09-15.
| Costco item | price | regular_price | instant_savings | What Costco's text says |
|---|---|---|---|---|
| Bounty Advanced Paper Towels, 12-count (US) | 27.39 USD | 32.99 USD | 5.60 | $5.60 OFF - valid 8/24/26 through 9/20/26 |
| Suncast 6' x 5' Modern Shed (US) | 649.99 USD | 799.99 USD | 150.00 | $150 OFF - valid 8/21/26 through 10/4/26 |
| POLYWOOD Long Beach Adirondack Chair, White (US) | 139.99 USD | 179.99 USD | 40.00 | $139.99 After $40 OFF |
| LG 6.0 cu. ft. Single Door Refrigerator (US) | 389.99 USD | null | null | Member-only item, price shown in cart - member_only true, price_in_cart_only true |
| Kirkland Signature Olive Oil, 3 L (Canada) | 30.99 CAD | null | null | no saving running |
On 5 of 5 instant-savings items the product record and the search row gave the same price and regular price. A bundle whose text reads "Price includes $450 savings" has one price only, so regular_price stays null rather than a computed number.
Which store, which price, which number, and what Costco does not publish
Two Costco stores, two currencies, French in Canada. Measured on 2026-09-15 across 30 products in 21 categories, 24 searches, 43 controlled cases and a check of 8 products against two separate Costco data sources. Four of these lines go against us.
country us (costco.com, USD) or ca (costco.ca, CAD); language fr gives French titles and descriptions in Canada. 24 of 24 searches and 30 of 30 product reads succeeded across both on 2026-09-15.
price is what you pay today, regular_price the price before the saving, instant_savings the gap, savings_text Costco's wording and savings_valid_from / savings_valid_through the dates. 5 of 5 instant-savings items gave the same numbers in search and in the product record.
member_only marks items only members can buy; price_in_cart_only marks prices Costco's website shows only in the cart. The price is still returned, with price_display saying how Costco shows it.
On 8 of 8 products, price, title, rating and availability matched both of Costco's own data sources the API reads. No HTML tags or entities in 121 payloads.
A Costco URL, its product number or an item number resolves to the same record: the rating and specifications of the product, the price and flags of the item, and every variant with its own price.
A keyword Costco answers with a category page (mattress, tv, furniture) returns that page's products with redirected_to; a misspelling returns the corrected results with matched_query; unrelated filler for a keyword with no match is removed and counted (8 of 8 nonsense keywords empty, 0 of 39 real queries emptied).
The UK, Mexico, Australia and Taiwan run a different Costco website, and other countries are not served either. Only the US and Canada are covered.
availability is Costco's online status, not a quantity or a specific warehouse. Prices are Costco's online prices.
Rating and review count are returned; the reviews themselves are not. Each item has one image.
On 30 sampled products manufacturer was filled on 15 and model on 13; a real order limit exists on 8 (Costco's no-limit default is returned as null). category_paths lists every category page an item sits on, not one ordered breadcrumb.
What people build with Costco
The jobs this data is most often used for.
endpoints
credit per call
Deal trackers record Costco's weekly instant savings with the regular price, the saving and the dates it runs, in the US and Canada.
Price-comparison sites match Costco items to other retailers by GTIN and compare the price members actually pay.
Brands monitor how their products are priced, rated and promoted on costco.com and costco.ca, including member-only listings.
Canadian shoppers' apps read costco.ca in English or French with the same fields.
What Costco data costs
The cheapest call here is 1 credit, so $15/mo (Pro) buys 10,000 of them — $1.50 per 1,000 credits. Credits roll over and never expire, and failed or blocked calls are not charged.
Full pricing →- 1,000 free credits on signup, no card
- One key, all 252 APIs, one credit pool
- Failed and blocked calls are never charged
- Credits roll over and never expire
Call it in two lines
Sign up, get 1,000 credits and one key that works on every engine. Then this is the whole protocol.
curl -X POST https://api.reefapi.com/costco/v1/search \
-H "x-api-key: $REEF_KEY" \
-H "content-type: application/json" \
-d '{"query":"coffee"}'import requests
r = requests.post(
"https://api.reefapi.com/costco/v1/search",
headers={"x-api-key": REEF_KEY},
json={
"query": "coffee"
},
)
print(r.json()["data"])Have a question? We got answers.
The questions people actually ask before wiring up Costco.
Get a free key →Which price is the one a Costco member pays?▾
price. It is the price after any instant saving that is running. regular_price is the price before the saving and is null when there is none; instant_savings is the difference. On 2026-09-15, 15 of the 24 products in Costco's own "instant savings" search carried a regular_price.
What do member_only and price_in_cart_only mean?▾
member_only is true for items only Costco members can buy; price_in_cart_only is true when Costco's website hides the price until the item is in the cart. The API still returns the price, with price_display reading shown, in_cart or not_shown. The LG 6.0 cu. ft. refrigerator read 389.99 USD, member_only true, price_in_cart_only true. Made-to-measure items such as custom window treatments have no price at all and return price null.
Item number or product number - which do I pass?▾
Either, or the Costco URL. The number in a Costco link (…product.100986754.html) is the product; the buyable variant has its own item number (1663899). product/detail resolves both: the rating and specifications belong to the product, the price and member flags to the item. Pass a product with sizes or colours and variants lists every item with its own price - a Nautica jacket returned 10.
Which countries and languages are covered?▾
The United States (costco.com, USD) and Canada (costco.ca, CAD), with French titles and descriptions in Canada via language fr. Search and product reads succeeded in both on 2026-09-15. Item numbers belong to one country: a US item asked in Canada returns NOT_FOUND. Costco's other countries run a different website and are not covered.
What happens when a search has no match, or Costco sends the keyword to a category?▾
When nothing matches, Costco fills its page with unrelated products; the API returns an empty result and counts them in fallback_results_dropped (8 of 8 nonsense keywords came back empty, 0 of 39 real queries were emptied). When Costco answers a keyword with a category page - mattress, tv, furniture - the API returns that category's products and says so in redirected_to. A keyword Costco sends to another Costco site, such as tires, returns an empty result with redirect_url.
Do the filters and sorts really apply?▾
Yes. coffee on 2026-09-15: 319 results, 19 with brand Kirkland Signature (every row Kirkland Signature). in_stock_only removed the unavailable rows (tv: 171 to 165). price_asc and price_desc come back in price order, rating in rating order; newest and most_viewed reorder the list. The brands to pass come back in filters_available with their counts.
What does Costco NOT publish here?▾
No unit price, no stock count (availability is a status), no warehouse-specific prices and no review texts. Items carry one image. Manufacturer and model are filled only where Costco publishes them (15 and 13 of 30 sampled products). category_paths lists the category pages an item appears on, not a single ordered breadcrumb.
What is the Costco API?▾
Costco API is a ReefAPI endpoint group for costco us and canada prices with instant savings, member-only items and savings dates kept apart. It returns live JSON through POST requests under /costco/v1.
Is the Costco API free to try?▾
Yes. ReefAPI starts with 1,000 free credits, no card required. Costco calls use the same shared credit balance as every other ReefAPI engine.
Do I need a Costco login or account?▾
No login to Costco 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 Costco 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 Costco API use?▾
Costco actions currently cost 1 credit per successful call. Failed or blocked calls are free, and all APIs draw from one credit pool.
Can I call Costco from an AI assistant or MCP client?▾
Yes. Connect ReefAPI once through MCP and your assistant can call costco actions with the same key, credit pool and JSON envelope used by normal REST requests.
Is the Costco API a Costco scraper?▾
It is the managed alternative to a DIY Costco 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 costco us and canada prices with instant savings, member-only items and savings dates kept apart back as clean JSON.
91 E-commerce & Marketplaces APIs on the same key
One key, one credit pool, one response envelope. If you are pulling Costco, you are one call away from the rest of the category — no second contract, no second integration.
Need something this API does not do?
Name the endpoint, the field, or a source we do not carry yet. We ship new APIs every week and you would be first to get the key. Real people read every message and reply the same day.
Try it on your own data before you pay anything
The call above is the real endpoint, not a recording. A free key gives you 1,000 credits, the other 251 APIs, and the same envelope everywhere.
Endpoints, parameters and credit costs on this page are read from the live catalog and cannot drift from what the API accepts. Field notes were captured on 2026-09-15.