# ShopGoodwill — US Goodwill charity auction marketplace

> Search LIVE ShopGoodwill listings — the US Goodwill charity auction marketplace, 650k+ open lots across 163 regional Goodwill sellers. Every row carries the auction facts that matter more than the price: current high bid, bid count, resolved end time and minimum next bid. Give query, or category_id, or seller_id (at least one of the three). The source serves a fixed 40 rows per page.
> ReefAPI engine `shopgoodwill` · 8 endpoints · clean JSON, no scraping or browsers to manage.

## How to call
- **Endpoint:** `POST https://api.reefapi.com/shopgoodwill/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). Send the key as `Authorization: Bearer <key>`, or put it in the URL (`?key=<key>`) when the client has no header field, as ChatGPT does.

## Endpoints

### POST https://api.reefapi.com/shopgoodwill/v1/search — 2 credits
Search LIVE ShopGoodwill listings — the US Goodwill charity auction marketplace, 650k+ open lots across 163 regional Goodwill sellers. Every row carries the auction facts that matter more than the price: current high bid, bid count, resolved end time and minimum next bid. Give query, or category_id, or seller_id (at least one of the three). The source serves a fixed 40 rows per page.

**Parameters:**
- `query` (string, optional) — Keyword text, 1-200 characters, matched against listing titles. At least one of query, category_id or seller_id is required.
- `category_id` (integer, optional) — Numeric ShopGoodwill category ID from the categories action (for example 10 = Clothing, 99 = Books, 15 = Art).
- `seller_id` (integer, optional) — Numeric regional Goodwill seller ID from the sellers action (for example 6 = Wooster OH, 2 = Santa Ana CA).
- `listing_type` (enum, optional) — Restrict to one sale format. Omit for every format. [one of: auction, buy_now, auction_with_buy_now]
- `min_price` (number, optional) — Lowest current price in USD, inclusive. Measured to bite: coin with min_price 100 returned 40 rows whose cheapest row was exactly 100.00.
- `max_price` (number, optional) — Highest current price in USD, inclusive.
- `pickup_only` (boolean, optional, default false) — Only lots that must be collected in person from the Goodwill location.
- `exclude_pickup_only` (boolean, optional, default false) — Drop the local-pickup-only lots and keep everything that ships.
- `one_cent_shipping_only` (boolean, optional, default false) — Only lots in the source's one-cent-shipping promotion.
- `ships_to_canada` (boolean, optional, default false) — Only lots the seller will ship to Canada.
- `international_shipping_only` (boolean, optional, default false) — Only lots with international shipping offered.
- `search_descriptions` (boolean, optional, default false) — Widen the keyword match from the title into the listing description.
- `sort` (enum, optional, default "ending_soonest") — Result ordering. Each value was verified to actually reorder the result against two control queries. [one of: ending_soonest, ending_latest, most_bids, fewest_bids, price_low, price_high]
- `page` (integer, optional, default 1) — One-based result page; the source serves a fixed 40 rows per page. last_page in the response is the final page that carries rows.

**Returns:** total (the source's own result count, uncapped), page, page_size 40, last_page, has_more, page_beyond_last, and listings[]: item_id, title, url, listing_type (auction / buy_now / auction_with_buy_now), current_price with price_basis (current_high_bid or fixed_price), currency USD, bid_count, starting_price, minimum_next_bid, buy_now_price, shipping_price, ends_at (ISO-8601 with the US Pacific offset), ends_at_local (the source's raw naive string), ends_at_is_placeholder, starts_at, seconds_remaining, ended, seller_id, category_id, category_name, quantity, is_stock_item, part_number and image_url. Measured on 373 rows over ten queries: every field above is populated except buy_now_price (100/373, only the buy-now formats) and part_number (13/373); quantity was 1 and is_stock_item false on all 373, because charity lots are one-of-a-kind.

**Example request body:**
```json
{
  "query": "vintage camera",
  "sort": "most_bids",
  "page": 1
}
```

### POST https://api.reefapi.com/shopgoodwill/v1/sold — 2 credits
Closed ShopGoodwill auctions — the same rows after the hammer, where current_price is the FINAL price the lot sold for and bid_count is the bidding that got it there. A sold-price comparable set for second-hand pricing. Covers a window of up to 30 days back from ending_before.

**Parameters:**
- `query` (string, optional) — Keyword text, 1-200 characters. At least one of query, category_id or seller_id is required.
- `category_id` (integer, optional) — Numeric category ID from the categories action.
- `seller_id` (integer, optional) — Numeric seller ID from the sellers action.
- `days_back` (integer, optional, default 7) — How many days before ending_before to include. The source accepts 1 to 30.
- `ending_before` (string, optional) — Latest auction end date to include, as YYYY-MM-DD. Defaults to today in US Pacific, the source's own clock.
- `listing_type` (enum, optional) — Restrict to one sale format. [one of: auction, buy_now, auction_with_buy_now]
- `min_price` (number, optional) — Lowest final price in USD, inclusive.
- `max_price` (number, optional) — Highest final price in USD, inclusive.
- `search_descriptions` (boolean, optional, default false) — Widen the keyword match into the listing description.
- `sort` (enum, optional, default "ending_soonest") — Result ordering. [one of: ending_soonest, ending_latest, most_bids, fewest_bids, price_low, price_high]
- `page` (integer, optional, default 1) — One-based result page; 40 rows per page.

**Returns:** Same listing shape as search, with current_price carrying the FINAL sale price, price_basis final_price, source_remaining_time 'Auction Ended', ended true and seconds_remaining 0; plus total, page, page_size 40, last_page, has_more and the window echoed as days_back and ending_before.

**Example request body:**
```json
{
  "query": "coin",
  "days_back": 7,
  "sort": "price_high"
}
```

### POST https://api.reefapi.com/shopgoodwill/v1/detail — 1 credit
Full public detail for one lot by the item_id search returns: description, every gallery image, the auction clock, the reserve state, the bid increment, shipping and handling, the pickup address of the Goodwill that listed it, and the complete public bid log.

**Parameters:**
- `item_id` (string, required) — Numeric ShopGoodwill item ID as returned by search or sold.

**Returns:** Every search field plus description and description_html, keywords, images[] and thumbnails[], category_path[] with IDs, bid_increment, max_quantity, has_reserve / reserve_met / reserve_price, handling_price, weight_lb, ships_internationally, pickup_only and pickup_location (street, city, state, zip, hours), seller (id, company_name, slug, shipper, url), seller_terms, shipping_policy, source_server_time, current_price_disagrees_with_bid_log, and bid_history with standing_bids[] and bid_log[] (source-masked bidder names, amounts, timestamps, retracted flag).

**Example request body:**
```json
{
  "item_id": "278936844"
}
```

### POST https://api.reefapi.com/shopgoodwill/v1/bids — 1 credit
The public bid log for one lot on its own: every bid placed with the source-masked bidder handle, the amount, the resulting price and the timestamp, plus the reserve state and whether the auction has closed. Works on live auctions as well as closed ones.

**Parameters:**
- `item_id` (string, required) — Numeric ShopGoodwill item ID as returned by search or sold.

**Returns:** item_id, title, url, current_price, bid_count, bidder_count, auction_closed, has_reserve, reserve_met, reserve_price, ends_at, standing_bids[] (one row per bidder: bidder, amount, placed_at, quantity_won) and bid_log[] in time order (bidder, bid_amount, price_after_bid, placed_at, retracted, high_bidder_after). Timestamps are published both resolved (placed_at) and raw (placed_at_local).

**Example request body:**
```json
{
  "item_id": "278936844"
}
```

### POST https://api.reefapi.com/shopgoodwill/v1/categories — 2 credits
The ShopGoodwill category taxonomy as the site's own search publishes it: two levels, 29 top-level departments and 239 subcategories, each with the numeric category_id the search action takes.

**Parameters:**
- `top_level_only` (boolean, optional, default false) — Return only the 29 departments without their subcategories.

**Returns:** categories[]: category_id, name, slug, level, parent_id, subcategory_count and nested subcategories[] with the same shape; plus top_level_count and total_count. The source's openItemCount is not published because it was 0 on all 268 nodes.

**Example request body:**
```json
{
  "top_level_only": false
}
```

### POST https://api.reefapi.com/shopgoodwill/v1/sellers — 1 credit
The directory of regional Goodwill organisations selling on the site (163 measured), with the numeric seller_id the search action takes and the US state and city each one ships and allows pickup from.

**Parameters:**
- `state` (string, optional) — Two-letter US state code; filtered by this engine over the source's full directory, which carries no state parameter of its own.
- `query` (string, optional) — Case-insensitive substring of the city or the organisation name; filtered by this engine over the source's full directory.

**Returns:** sellers[]: seller_id, organisation, state, city, label and url; plus total (the source's full directory size) and returned (after any engine-side state/query filter).

**Example request body:**
```json
{
  "state": "OH"
}
```

### POST https://api.reefapi.com/shopgoodwill/v1/seller — 1 credit
The public profile of one regional Goodwill seller: organisation name, mailing address, mission statement, return policy and customer service note.

**Parameters:**
- `seller_id` (integer, required) — Numeric seller ID from the sellers action.

**Returns:** seller_id, organisation, street, city, state, zip, customer_service, mission_statement, return_policy and url. Fields the source publishes empty are returned as null, never as an empty string.

**Example request body:**
```json
{
  "seller_id": 6
}
```

### POST https://api.reefapi.com/shopgoodwill/v1/seller_items — 1 credit
The listings one regional Goodwill seller currently has open, as the site's own seller storefront shows them.

**Parameters:**
- `seller_id` (integer, required) — Numeric seller ID from the sellers action.

**Returns:** seller_id, returned and listings[]: item_id, title, url, current_price, currency, bid_count, minimum_next_bid, buy_now_price, listing_type, ends_at and ends_at_local, starts_at, category_id, category_name, image_url. This storefront surface returns a short, source-chosen slice (5 rows for 5 of 5 sellers measured) and carries no paging handle; use search with seller_id for the full, pageable set.

**Example request body:**
```json
{
  "seller_id": 6
}
```

## At scale
- **Volume:** 5M+ requests a day, measured at 60 requests a second across the fleet with no
  central bottleneck. Per-key limits are raised for high-volume accounts; volume pricing on request.
- **Missing a source:** tell us a site we do not cover and it becomes an engine. A customer asked
  for bestprice.gr on 21 Sep 2026 and it was in the catalog on 22 Sep.
- **Support:** 2 minute median time from a question in the live chat to the first answer. Setup
  help included, no support tier to buy.
- **One key, one credit pool** across every API. No per-site plans, no separate subscriptions.

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