Costco API & Scraper
The Costco API turns costco.com and costco.ca into clean JSON in four actions: search, product/detail, category and search/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.
Pick the store with country (us or ca) and, in Canada, language (en or fr); prices come back in USD or CAD. Every product carries the price you pay today and, separately, the regular price and the instant saving, because Costco shows a manufacturer's saving as two numbers plus a line of text such as "$5.60 OFF" - the API returns price 27.39, regular_price 32.99, instant_savings 5.60 and savings_text, plus the dates the saving runs (savings_valid_from, savings_valid_through, price_valid_through). Member-only items and items whose price Costco only shows in the cart are flagged with member_only and price_in_cart_only, so the number is never mistaken for a public shelf price. Rows also carry the rating and review count, availability, delivery programs, badges such as Costco Direct or Online Only, real order limits, the GTIN, the category pages an item is listed on and a costco.com or costco.ca link. product/detail accepts an item number, the product number from a Costco URL or the URL itself and adds the description, feature bullets, specifications, promotions, the shipping note and every size and colour variant with its own price. Verification on 2026-09-15: 24 of 24 searches and 30 of 30 product reads across both countries succeeded, 43 of 43 controlled cases passed, and on 8 of 8 products price, title, rating and availability matched two separate Costco data sources. No Costco membership or account needed - one ReefAPI key and the standard { ok, data, meta, error } envelope.
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.
Real request and response JSON
Captured from the indexed primary action, search, on .
{
"method": "POST",
"url": "https://api.reefapi.com/costco/v1/search",
"headers": {
"x-api-key": "$REEF_KEY",
"content-type": "application/json"
},
"body": {
"query": "coffee"
}
}{
"ok": true,
"meta": {
"api": "costco",
"endpoint": "search",
"mode": "live",
"latency_ms": 1921.4,
"record_count": 24,
"bytes": 123599,
"cache_hit": false,
"country": "us",
"requests": 1,
"pagination": {
"page": 1,
"page_size": 24,
"has_more": true,
"total": 321
}
},
"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"
}
}What the Costco API does
| Action | Description | Concrete use case | Key params |
|---|---|---|---|
| search | Search Costco (United States or Canada) by keyword. Each product comes with the price after instant savings and, separately, the regular price and the saving, Costco's own savings text and the date the price is valid through, member-only and price-in-cart flags, rating and review count, availability, delivery programs, badges and the category pages it sits in. A keyword Costco answers with a category page is followed; unrelated padding for a keyword with no match is removed and counted. Sort by price, rating, newest or most viewed; filter by brand or in-stock. | Pricing teams call search to search Costco (United States or Canada) by keyword. | query, country, language, page, page_size, ... |
| product/detail | The full Costco record by item number, product number or URL: title, brand, manufacturer, model, GTIN, the price after instant savings with the regular price and saving kept apart, savings text and validity date, promotions, member-only and price-in-cart flags, shipping note, rating and review count, description, feature bullets, specifications, badges, delivery programs, order limit, availability, category pages and every variant (size, colour) with its own price. | Marketplace operators call product/detail to get the full Costco record by item number, product number or URL. | item_number, country, language, max_rotations |
| category | Every product on one Costco category page (for example mattresses, televisions, kirkland-signature-groceries), paged, with the same rows, sorting and filters as search, plus the category's breadcrumb. | Catalog enrichment teams call category to get every product on one Costco category page (for example mattresses, televisions, kirkland-sign…. | category, country, language, page, page_size, ... |
| search/suggest | Costco's search-box suggestions for what a shopper has typed: products (with item number and image), brands, categories, popular searches and warehouse locations. | Retail analysts call search/suggest to get costco's search-box suggestions for what a shopper has typed. | query, country, language, max_rotations |
Call search from your stack
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"])const res = await fetch("https://api.reefapi.com/costco/v1/search", {
method: "POST",
headers: {
"x-api-key": process.env.REEF_KEY,
"content-type": "application/json",
},
body: JSON.stringify({
"query": "coffee"
}),
});
const { ok, data, meta, error } = await res.json();Ask your MCP-connected assistant: call reefapi.costco.search with {"query":"coffee"}.Who uses this API and why
- 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.
Questions developers ask before integrating
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.