Costco Analysis

This project contains scripts to fetch and analyze Costco receipt data using the Costco API. Note that you need to log in to costco.com manually and look at the network requests to get the bearer token, the client ID, and the client identifier.

Setup

1. Install dependencies:

   uv sync

2. Set up environment variables:

   cp .env.example .env

   Then edit .env and add your actual Costco API credentials. You can get these by looking at the network requests in your browser when you're logged in to costco.com and looking at the headers in the graphql requests.

   • COSTCO_BEARER_TOKEN - Your bearer token
   • COSTCO_CLIENT_ID - Your client ID
   • COSTCO_CLIENT_IDENTIFIER - Your client identifier

Scripts

• fetch_receipts.py - Fetches receipt lists for date ranges
• fetch_receipt_details.py - Fetches detailed receipt information by barcode
• fetch_all_receipt_details.py - Batch fetches detailed receipts for all barcodes found in data files

Environment Variables

• COSTCO_BEARER_TOKEN - Your Costco API bearer token
• COSTCO_CLIENT_ID - Your Costco API client ID
• COSTCO_CLIENT_IDENTIFIER - Your Costco API client identifier

Usage

All scripts will automatically load the required credentials from your .env file. Make sure to set up all the environment variables before running any scripts.

python fetch_receipts.py
python fetch_all_receipt_details.py

CSV Export

Use the generate_csv_file.py script to flatten all downloaded receipt JSON into two CSVs at the repo root:

python generate_csv_file.py

• costco-items.csv — one row per line item with transaction_date, transaction_barcode, warehouse_name, transaction_type, item_number, description, description2, combined_description, item_department_number, item_unit_price, item_amount, item_quantity.
• costco-receipts.csv — one row per receipt with transaction_date, transaction_barcode, warehouse_name, transaction_type, subtotal, taxes, total, instant_savings, total_item_count.

The queries used by the script live in generate_csv_file.py (ITEMS_QUERY and RECEIPTS_QUERY). They read directly from data/receipts/*.json via DuckDB's read_json_auto.

Dashboard

index.html is a self-contained ECharts dashboard that consumes both CSVs. Serve the directory locally and open it:

python -m http.server 8000
# then open http://localhost:8000/index.html

Three tabs:

• Item Trends — original price-over-time chart and data table, grouped by item_number (descriptions are shown as the latest seen for each item).
• Price Index — personal Costco price index. Items bought 4+ times are normalized to 100 at their baseline (avg of first 2 purchases); the chart plots the monthly mean across qualified items. Includes a "biggest movers" table.
• Departments — monthly stacked spend chart for the top 10 departments, plus a lifetime spend table showing the top items in each department.