# Costco API scraper — costco.com and costco.ca: search products, read the full item record with the price after instant savings and the regular price kept apart, savings validity dates, member-only and price-in-cart flags, order limits, ratings, specifications and variants; browse categories and search suggestions. No account, no browser.

> 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.
> ReefAPI engine `costco` · 4 endpoints · clean JSON, no scraping or browsers to manage.

## How to call
- **Endpoint:** `POST https://api.reefapi.com/costco/v1/<action>` with a JSON body.
- **Auth:** header `x-api-key: <YOUR_REEFAPI_KEY>` — create one free (1,000 credits, no card): https://reefapi.com/signup
- **Response (every call):** `{ ok: boolean, data: ..., meta: { record_count, credits, ... }, error: { code, message } }` — branch on `ok`. Failed calls are free except verified SHEIN NOT_FOUND on product/detail and price (4 credits).
- **One key + one shared credit pool** across every ReefAPI API. Per-call credits are listed on each endpoint below.
- **Use it from an AI agent (MCP):** connect `https://api.reefapi.com/mcp` (remote streamable-http, `Authorization: Bearer <key>`) and your assistant can call these actions directly.

## Endpoints

### POST /costco/v1/search — 1 credit
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.

**Parameters:**
- `query` (string, required) — Words a shopper would type on Costco.
- `country` (enum, optional, default "us") — Which Costco store: us (costco.com, USD) or ca (costco.ca, CAD). A costco.ca URL sets it by itself. Costco's other countries run a different platform. [one of: us, ca]
- `language` (enum, optional, default "en") — Language of titles and texts. French exists only on costco.ca. [one of: en, fr]
- `page` (integer, optional, default 1) — Result page, from 1.
- `page_size` (integer, optional, default 24) — Products per page (Costco's own page shows 24).
- `sort` (enum, optional, default "relevance") — Costco's own sort orders. [one of: relevance, price_asc, price_desc, rating, newest, most_viewed]
- `brand` (string, optional) — Only one brand, spelled as `filters_available.brands` lists it.
- `in_stock_only` (boolean, optional, default false) — true: hide products Costco marks unavailable (the site's 'Hide Unavailable Items').
- `include_fallback_results` (boolean, optional, default false) — When nothing matches, Costco fills the page with unrelated products. They are dropped and counted; true returns them separately in `fallback_results`.
- `max_rotations` (integer, optional, default 3) — How many fresh exits to try before giving up.

**Returns:** results[]{item_number, product_id, title, brand, model, gtin, url, image, price, regular_price, instant_savings, savings_text, price_valid_through, marketing_statement, price_range{min, max}, currency, member_only, price_in_cart_only, price_display, rating, review_count, rating_scale, availability, delivery_status, programs[], online_only, warehouse_only, costco_direct, badges[], has_variants, max_order_quantity, fsa_eligible, category_paths[]}, count, total_results, page, page_size, has_more, fallback_results_dropped, sponsored_dropped, duplicates_dropped, filters_available{brands[], price_ranges[], ratings[], categories[] ({value, count})}, country, language, currency, query, matched_query, redirected_to, redirect_url, sort_applied

**Example request body:**
```json
{
  "query": "coffee"
}
```

### POST /costco/v1/product/detail — 1 credit
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.

**Parameters:**
- `item_number` (string, required) — A Costco item number (1789247), a product number (the number in a product URL, 4000262621) or a costco.com / costco.ca product URL.
- `country` (enum, optional, default "us") — Which Costco store: us (costco.com, USD) or ca (costco.ca, CAD). A costco.ca URL sets it by itself. Costco's other countries run a different platform. [one of: us, ca]
- `language` (enum, optional, default "en") — Language of titles and texts. French exists only on costco.ca. [one of: en, fr]
- `max_rotations` (integer, optional, default 3) — How many fresh exits to try before giving up.

**Returns:** product{product_id, item_number, title, brand, manufacturer, model, gtin, url, images[], price, regular_price, instant_savings, savings_text, price_valid_through, marketing_statement, promotions, savings_valid_from, savings_valid_through, price_range{min, max}, currency, member_only, price_in_cart_only, price_includes_shipping_handling, shipping_note, rating, review_count, rating_scale, description, features[], specifications{name: value}, badges[], programs[], online_only, costco_direct, buyable, published, max_order_quantity, fsa_eligible, variants[]{item_number, attributes{}, price, regular_price, instant_savings, member_only, price_in_cart_only, buyable, published, max_order_quantity, fsa_eligible}, variant_count, availability, delivery_status, category_paths[], start_date}, country, language

**Example request body:**
```json
{
  "item_number": "1789247"
}
```

### POST /costco/v1/category — 1 credit
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.

**Parameters:**
- `category` (string, required) — A Costco category page: its name as in the URL (mattresses), its path (/mattresses.html) or the full URL. `category_paths` on any product lists them.
- `country` (enum, optional, default "us") — Which Costco store: us (costco.com, USD) or ca (costco.ca, CAD). A costco.ca URL sets it by itself. Costco's other countries run a different platform. [one of: us, ca]
- `language` (enum, optional, default "en") — Language of titles and texts. French exists only on costco.ca. [one of: en, fr]
- `page` (integer, optional, default 1) — Result page, from 1.
- `page_size` (integer, optional, default 24) — Products per page (Costco's own page shows 24).
- `sort` (enum, optional, default "relevance") — Costco's own sort orders. [one of: relevance, price_asc, price_desc, rating, newest, most_viewed]
- `brand` (string, optional) — Only one brand, spelled as `filters_available.brands` lists it.
- `in_stock_only` (boolean, optional, default false) — true: hide products Costco marks unavailable (the site's 'Hide Unavailable Items').
- `max_rotations` (integer, optional, default 3) — How many fresh exits to try before giving up.

**Returns:** results[]{item_number, product_id, title, brand, model, gtin, url, image, price, regular_price, instant_savings, savings_text, price_valid_through, marketing_statement, price_range{min, max}, currency, member_only, price_in_cart_only, price_display, rating, review_count, rating_scale, availability, delivery_status, programs[], online_only, warehouse_only, costco_direct, badges[], has_variants, max_order_quantity, fsa_eligible, category_paths[]}, count, total_results, page, page_size, has_more, fallback_results_dropped, sponsored_dropped, duplicates_dropped, filters_available{brands[], price_ranges[], ratings[], categories[] ({value, count})}, country, language, currency, category, breadcrumb[]{name, url}, sort_applied

### POST /costco/v1/search/suggest — 1 credit
Costco's search-box suggestions for what a shopper has typed: products (with item number and image), brands, categories, popular searches and warehouse locations.

**Parameters:**
- `query` (string, required) — What a shopper has typed so far (Costco suggests from 4 characters).
- `country` (enum, optional, default "us") — Which Costco store: us (costco.com, USD) or ca (costco.ca, CAD). A costco.ca URL sets it by itself. Costco's other countries run a different platform. [one of: us, ca]
- `language` (enum, optional, default "en") — Language of titles and texts. French exists only on costco.ca. [one of: en, fr]
- `max_rotations` (integer, optional, default 3) — How many fresh exits to try before giving up.

**Returns:** suggestions[]{type, text, item_number, product_id, brand, image, url, address}, count, query, country, language

**Example request body:**
```json
{
  "query": "coffee"
}
```

## More
- Try it live, no code: https://reefapi.com/playground?engine=costco
- Human docs page: https://reefapi.com/docs/costco
- Overview page: https://reefapi.com/costco-api
- Every ReefAPI API in one file (for your AI): https://reefapi.com/llms-full.txt