Costco via Scavio

Search Costco, read items in full, compare the online price with the shelf price at specific warehouses, check warehouse stock, and pull gas prices, the member coupon book, deal feeds and clearance markdowns. All endpoints return structured JSON.

When to trigger

Use this skill when the user asks to:

• Find products on costco.com or costco.ca by keyword, item number, category, brand, price band or rating
• Look up a Costco item by item number, product id or a pasted costco.com product URL
• Compare the online price with the in-warehouse price at one or more Costco warehouses
• Check whether a warehouse has an item in stock, or offers pickup or same-day delivery for it
• Find Costco warehouses near a zip code or coordinates, with hours, departments and services
• Get current regular, premium and diesel prices at Costco gas stations
• Read the current Costco member coupon book, or the new, treasure hunt, while-supplies-last and on-sale deal feeds
• Find clearance and manager-markdown items at a specific warehouse
• Read customer reviews for a Costco product with the rating distribution
• Monitor Costco pricing and promotions, or enrich a catalog with Costco item data

Setup

Get a free API key at scavio.dev (50 free credits to get started, no card required):

export SCAVIO_API_KEY=sk_live_your_key

If you do not have a key yet

An agent running this skill without SCAVIO_API_KEY set will get 401 on every call below. The whole path from nothing to a working key is self-serve:

1. Sign up at dashboard.scavio.dev - email or Google, no card required.
2. A key is created for the account automatically at signup. It is on the dashboard under API Keys, ready to copy.
3. A new account starts with 50 credits. Endpoints in this skill cost 1 credit each unless the table below says otherwise.

When the balance runs out the API answers 402 with a JSON body carrying billing_url. Topping up needs no code change - the same key keeps working. The smallest purchase is 2,500 credits for $25, and monthly plans work out cheaper per credit if the usage is steady rather than one-off.

Every request is a POST with a JSON body and:

Authorization: Bearer $SCAVIO_API_KEY

Endpoints

Base URL: https://api.scavio.dev. Most Costco endpoints cost 1 credit; the multi-warehouse ones scale with the number of warehouses.

Countries. country is us (costco.com, default) or ca (costco.ca) on every endpoint except coupons, which is US only and takes no parameters. Search, product and warehouses also accept uk, au, mx, jp, kr and tw for keyword, sort and paging only - no warehouse prices and no gas outside the US and Canada.

Workflow

1. Find a warehouse: call /costco/warehouses with zip (US) or latitude + longitude. Read warehouses[].warehouse_id (e.g. 1062). /costco/autocomplete also resolves a town name to warehouses.
2. Find items: call /costco/search with query (or /costco/category with a slug from /costco/categories). Pass warehouse_id to get that warehouse's shelf price and stock on every row in the same 1 credit.
3. Item detail: call /costco/product with item_id, or up to 20 at once with item_ids.
4. Price across warehouses: call /costco/prices with the item and warehouse_ids (up to 10). The online price is always included.
5. Stock: call /costco/availability with item_number and warehouse_ids.
6. Reviews: call /costco/reviews with product_id - the costco.com page id, not the item number.

Two ids, not one. item_number is the number on the shelf tag and the receipt; product_id is the costco.com page id. Product, prices and availability accept either (or a product URL). Reviews takes product_id only.

Pagination

• Search, category and deals: page (1-based, up to 500) and page_size (default 24, up to 120; up to 100 on uk, au, mx, jp, kr and tw). The response carries total_results and total_pages. Each page is 1 credit, so state the budget before looping.
• Reviews: page and limit (default 25, up to 100). Stop at total_pages.
• Clearance: pages is how many result pages of 120 to scan (default 3, up to 5); still 1 credit.
• Product, prices, availability, warehouses, gas, coupons, categories, autocomplete: no paging.

Parameters

Search (/search), Category (/category), Deals (/deals)

On uk, au, mx, jp, kr and tw, sending warehouse_id, brands, a price or rating filter, on_sale, in_stock or in_warehouse is a 400, and so is sort_by: newest.

Categories (/categories)

Product (/product)

Prices (/prices)

Availability (/availability)

Reviews (/reviews)

Warehouses (/warehouses) and Gas (/gas)

Clearance (/clearance)

Autocomplete (/autocomplete)

Coupons (/coupons)

No parameters. Send an empty JSON object: {}.

Examples

curl -X POST https://api.scavio.dev/api/v1/costco/prices \
  -H "Authorization: Bearer $SCAVIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"item_id": "1492456", "warehouse_ids": ["1062", "1107"]}'

import requests

BASE = "https://api.scavio.dev"
# Your key from https://scavio.dev. Load it from your environment or secret
# store in real code - keep it out of source control.
API_KEY = "sk_your_key_here"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}

def costco(endpoint, body):
    r = requests.post(f"{BASE}/api/v1/costco/{endpoint}", headers=HEADERS, json=body)
    r.raise_for_status()
    return r.json()["data"]

# 1. Nearest warehouses to a zip code
wh = costco("warehouses", {"zip": "10025", "limit": 5})
warehouse_id = wh["warehouses"][0]["warehouse_id"]          # "1062"

# 2. Search with that warehouse's shelf price on every row (still 1 credit)
found = costco("search", {"query": "olive oil", "warehouse_id": warehouse_id, "page_size": 5})
for row in found["results"]:
    shelf = row.get("warehouse") or {}
    print(row["title"], row["price"], shelf.get("price"), shelf.get("price_code"))

# 3. Online vs in-warehouse price at two warehouses (1 credit for up to 9)
prices = costco("prices", {"item_id": "1492456", "warehouse_ids": ["1062", "1107"]})
item = prices["items"][0]
print(item["online"]["final_price"], [(w["warehouse_id"], w["final_price"]) for w in item["warehouses"]])

# 4. Stock at the warehouse (status only, never a unit count)
stock = costco("availability", {"item_number": "1492456", "warehouse_ids": [warehouse_id]})

# 5. Reviews take product_id, not item_number
reviews = costco("reviews", {"product_id": "100334960", "sort_by": "lowest_rating", "limit": 25})
print(reviews["rating"]["average"], reviews["total_pages"])

Gas, coupons, deals and clearance:

gas = costco("gas", {"zip": "90001", "limit": 5})
for s in gas["stations"]:
    print(s["name"], s["distance_miles"], s["prices"])          # regular / premium / diesel

book = costco("coupons", {})
print(book["valid_from"], book["valid_to"], book["count"])

deals = costco("deals", {"type": "while_supplies_last", "page_size": 5})

markdowns = costco("clearance", {"warehouse_id": "1062", "query": "snacks", "pages": 2})
for row in markdowns["results"]:
    print(row["title"], row["price"], row["warehouse"]["price"], row["warehouse"]["price_code"]["meaning"])

Response shapes

Every response uses the envelope { data, response_time, credits_used, credits_remaining }. Key data fields:

• search / category / deals - country, query, category, redirected_to_category, corrected_query, warehouse_id, total_results, page, page_size, total_pages, count, results[], facets[] (deals also type). A row: position, product_id, item_number, title, brand, categories, url, image, rating, reviews_count, price, original_price, on_sale, currency, delivery_availability, promotions, member_only, buyable, fsa_eligible, sold_in_warehouse, max_order_quantity, program_types, first_listed, variants_count, and with warehouse_id a warehouse object (warehouse_id, price, availability, price_code {ending, meaning}).
• product - country, count, not_found[], products[] (product_id, item_number, id, title, url, image, description, features[], specifications[] {name, value}, rating, reviews_count, price, currency, delivery_fee, promotions[], member_only, buyable, fsa_eligible, limit_one_per_order, min_order_quantity, max_order_quantity, reviews_eligible, department, program_types, first_listed, variants[]).
• prices - country, count, items[] (item_number, found, online {price, discount, final_price, currency, promotions[]}, warehouses[] {warehouse_id, available, price, discount, final_price, currency, promotions[], price_code}). A promotion: promotion_id, type, amount_off, start_date, end_date, order_limit, member_limit, text.
• availability - item_number, count, warehouses[] (warehouse_id, in_warehouse, channels {in_warehouse, warehouse_pickup, same_day_delivery}, each with status). Status values: in_stock, low_stock, out_of_stock, not_available.
• reviews - product_id, product_title, rating {average, count, recommended_count, distribution}, total_results, page, limit, total_pages, count, reviews[] (review_id, rating, title, text, author, location, submitted_at, recommended, verified_purchaser, helpful_votes, not_helpful_votes, photos, language, syndicated).
• warehouses - country, location, count, warehouses[] (warehouse_id, name, address, phone, latitude, longitude, distance_miles, opened, region, hours, business_hours, pharmacy_hours, tire_center_hours, gas_station {hours, prices} or null, departments, services, specialty_departments, warehouse_pickup, ship_to_warehouse, upcoming_holidays, currency).
• gas - country, currency, location, count, stations[] (warehouse_id, name, address, latitude, longitude, distance_miles, prices {regular, premium, diesel}, hours).
• coupons - country, valid_from, valid_to, count, coupons[] (title, item_number, product_id, discount {amount_off, final_price, text}, applies_to, coupon_type, limits, details, terms, url).
• clearance - country, warehouse_id, query, category, products_scanned, count, results[] (search rows with warehouse), price_code_legend, note.
• categories - parent_category_id, count, categories[] (category_id, name, slug).
• autocomplete - query, suggestions[], warehouses[] (warehouse_id, name, address, city, state, zip, country).

A prices response (captured, item 1492456 at warehouse 1062):

{
  "data": {
    "country": "us",
    "count": 1,
    "items": [
      {
        "item_number": "1492456",
        "found": true,
        "online": {
          "price": 20.99,
          "discount": 4,
          "final_price": 16.99,
          "currency": "USD",
          "promotions": [
            {
              "amount_off": 4,
              "start_date": "2026-09-28T07:00:00Z",
              "end_date": "2026-10-12T06:59:00Z",
              "order_limit": null,
              "member_limit": 6
            }
          ]
        },
        "warehouses": [
          {
            "warehouse_id": "1062",
            "available": true,
            "price": 17.99,
            "discount": 4,
            "final_price": 13.99,
            "currency": "USD",
            "price_code": { "ending": "99", "meaning": "regular_price" }
          }
        ]
      }
    ]
  }
}

A search row with warehouse_id (captured, "olive oil" at warehouse 1062):

{
  "position": 1,
  "product_id": "100334841",
  "item_number": "692731",
  "title": "Kirkland Signature, Organic Extra Virgin Olive Oil, 2 L",
  "brand": "Kirkland Signature",
  "rating": 4.8,
  "reviews_count": 6484,
  "price": 20.99,
  "currency": "USD",
  "url": "https://www.costco.com/p/-/kirkland-signature-organic-extra-virgin-olive-oil-2-l/100334841",
  "warehouse": {
    "warehouse_id": "1062",
    "price": 15.59,
    "availability": "in_stock",
    "price_code": { "ending": "59", "meaning": "other" }
  }
}

Price codes

price_code reads the cents of the warehouse shelf price: 99 regular_price, 97 clearance, 00 and 88 manager_markdown, 49/79/89 special_buy, anything else other. It is the decode Costco members use for shelf tags; Costco does not publish it, so treat it as a strong hint, not a guarantee. It is computed from the warehouse price only, never the online price.

Guardrails

• price on search rows and online on prices is the costco.com (or costco.ca) online price. The warehouse shelf price is warehouse.price / warehouses[].price, and it is often lower. Never present one as the other.
• Availability is a status per warehouse (in_stock, low_stock, out_of_stock, not_available), never a quantity. Do not invent unit counts.
• Clearance covers only items Costco lists online; warehouse-only items with no costco.com page cannot appear. A clearance item can already be out_of_stock at that warehouse - report warehouse.availability with it.
• special_buy endings are common on regular grocery prices, so they are off by default in clearance. Add them only when the user asks.
• Reviews take product_id, which is a different number from the item number. Get it from search or product first.
• Coupons are US only and take no parameters; the whole book is 1 credit.
• Non-default sort_by values broaden matching on Costco's side, so results can look less relevant than best_match.
• Multi-warehouse calls cost more: prices at 10 warehouses is 2 credits, availability is 1 per 5 warehouses, gas by warehouse_ids on costco.ca is 2 per warehouse. State the spend before fanning out.
• Never fabricate item numbers, prices, stock, gas prices or coupon terms. Only return what the API returned, and surface the product url so the user can verify.

Failure handling

• 400 means an invalid or missing parameter (no query, in_warehouse without warehouse_id, more than 10 warehouse_ids, a us/ca-only filter on another country, an unknown US zip) - fix the body and retry.
• 401 means the API key is invalid or missing. Check SCAVIO_API_KEY.
• 402 means the balance is out of credits. The body carries billing_url.
• 404 on /product means none of the ids matched anything; that call is billed. When some ids match, the rest are listed in not_found[] and the call succeeds.
• 429 means rate or usage limit exceeded. Wait before retrying. See rate limits.
• 502 / 503 mean Costco data is temporarily unavailable - wait a few seconds and retry, up to a few times.
• If search returns nothing, drop the filters or try broader keywords.
• If SCAVIO_API_KEY is not set, prompt the user to export it before continuing.

SDKs

pip install scavio==0.18.0

from scavio import ScavioClient

client = ScavioClient()  # reads SCAVIO_API_KEY

wh = client.costco.warehouses(zip="10025", limit=5)
found = client.costco.search("olive oil", warehouse_id="1062", page_size=5)
prices = client.costco.prices(item_id="1492456", warehouse_ids=["1062", "1107"])
gas = client.costco.gas(zip="90001", limit=5)
book = client.costco.coupons()
markdowns = client.costco.clearance(warehouse_id="1062", query="snacks")

npm install scavio@0.18.0

import { Scavio } from "scavio";

const scavio = new Scavio(); // reads SCAVIO_API_KEY
const found = await scavio.costco.search({ query: "olive oil", warehouse_id: "1062", page_size: 5 });
const prices = await scavio.costco.prices({ item_id: "1492456", warehouse_ids: ["1062", "1107"] });
const book = await scavio.costco.coupons();

MCP: the Scavio MCP server exposes all 13 endpoints as tools (search_costco, get_costco_prices, get_costco_availability, get_costco_gas_prices, get_costco_coupons, get_costco_clearance and the rest). Costco is opt-in: add costco to SCAVIO_PLATFORMS.

{
  "mcpServers": {
    "scavio": {
      "command": "npx",
      "args": ["-y", "@scavio/mcp-server@0.16.1"],
      "env": {
        "SCAVIO_API_KEY": "sk_live_your_key",
        "SCAVIO_PLATFORMS": "default,costco"
      }
    }
  }
}

Docs

Full reference per endpoint: Costco search, prices, availability, gas, coupons, clearance. Overview: Costco API.