A collector adds an item to an app and opens its value screen. A useful answer includes a price estimate, the version of the item being compared, and enough evidence to understand the result. A sealed set, an incomplete set, and a collection of spare pieces need different comparison groups even when their titles share a product number.
This guide builds that screen around SoldFetch sold-search observations. Your backend retrieves candidate listings, your application reviews their identity, and a saved snapshot supplies the estimate and supporting examples. The collection model, review rules, and valuation presentation belong to your app.
All amounts and records in the worked example are synthetic. The example describes a product workflow, not a current valuation or a customer deployment.
Define a collectible before estimating its value
Start with one category whose identity you can describe consistently. For a construction set, store the manufacturer, set number, edition, completeness, and sealed status. A graded card needs different fields, such as set, card number, language, grader, and grade. The trading-card pipeline explains how to review those distinctions.
Give each comparison group a stable identifier in your database. Two users who own the same edition in the same condition can share one evidence snapshot. A user who opens the box now needs a different group; changing the quantity owned does not require another market search.
Keep ownership records separate from comparison groups:
| Record | Example application fields | Purpose |
|---|---|---|
| Collection entry | user ID, collectible ID, quantity, purchase cost | Describes what one collector owns. |
| Comparison group | product identity, condition policy, marketplace, currency | Defines which listings can be compared. |
| Evidence snapshot | reviewed listing IDs, source times, rule version, summary | Explains the estimate shown to users. |
A purchase cost is the collector's own input. SoldFetch does not return their acquisition history or verify the condition of their physical item.
Retrieve candidates from your backend
Keep the API key on your server. A mobile client or browser requests a summary from your application, and a background worker performs collection when the corresponding snapshot needs a refresh. Check capabilities for data availability and enabled marketplaces before starting.
This request illustrates a search for one sealed set:
curl --fail-with-body --get 'https://soldfetch.com/v1/scrape' \
--data-urlencode 'keyword=lego 10281 bonsai tree sealed' \
--data-urlencode 'ebaySite=ebay.com' \
--data-urlencode 'sold=true' \
--data-urlencode 'exactMatch=true' \
--data-urlencode 'count=40' \
--data-urlencode 'page=1' \
--header "API-KEY: $SOLDFETCH_API_KEY"
The set number and sealed wording are search terms. They are not guaranteed identity filters. exactMatch=true excludes explicitly marked loose matches; it does not certify the product, edition, or completeness. Inspect candidates using your inclusion rules and enrich only ambiguous records through the item endpoint.
Read soldPrice, soldCurrency, url, itemId, scrapedAt, and quality.priceBasis from returned rows. Save the full request, response warnings, and source timestamps for your internal audit. Bound pagination and stop on empty or repeated pages. The Python search tutorial covers collection in detail.
Build a reviewed evidence snapshot
Add your own review status, comparison-group assignment, reason, and policy version alongside each untouched listing row. Include a candidate only when its identity matches the intended group. Keep unresolved bundles and unclear condition in a review queue.
For this example, summarize displayed item prices in USD, excluding shipping. Reject missing or nonfinite amounts, incompatible currencies, and range_lower_bound observations. Deduplicate by marketplace and item ID so a repeated listing does not receive extra weight.
The offline example also requires observations no older than 24 hours and at least five accepted listings. These are illustrative application policies, not SoldFetch guarantees or universal statistical thresholds. Choose them deliberately for your category and show a limited-evidence state when they are not met.
Five accepted synthetic displayed amounts are USD 38, 40, 42, 44, and 46. Their median is USD 42. The companion excludes a different comparison group, a price-range lower bound, a duplicate, and an old observation before calculating that result. Your app may use this reviewed median as an input to its estimate while keeping the price basis visible.
Displayed listing prices are not independently verified final payments or accepted-offer amounts. Source-reported sale dates are also unverified. Use scrapedAt to explain when evidence was observed; a refresh timestamp does not establish when an item sold. The price differences guide explains these distinctions.
Show an estimate users can inspect
A compact item screen can present the synthetic result like this:
| Field | Example display |
|---|---|
| Item | One complete sealed set, identified edition |
| Estimated item value | USD 42, based on the median displayed comparable price |
| Evidence | Five reviewed comparable listings |
| Price basis | Item amounts, excluding shipping |
| Observed | October 27, 2026 at 08:00 UTC |
| Supporting examples | A small selection, each linked to its original eBay listing |
| Context | Final accepted-offer amounts and sale dates are unverified |
The screen should distinguish a missing estimate from a zero value. If one item lacks sufficient evidence, keep it visibly unpriced. A collection summary can show a subtotal for priced entries and the number still awaiting an estimate. Multiplying quantities by estimates does not remove the uncertainty in each item's evidence.
On a paid SoldFetch plan, Terms section 9.2 permits derived valuations and transformed analyses for paying and free-tier users of your app. Your end users do not need their own SoldFetch subscription. The same section permits a small selection of linked recent sold examples as supporting evidence, subject to its conditions.
Your app must add material analysis or presentation. Keep raw API access and bulk redistribution out of the user interface, and respect third-party content rights. A listing link does not grant permission to reuse its photographs. The fixtures use reserved example.com URLs; production examples must link to the corresponding eBay listing returned by the service.
Share refresh work across the collection
Schedule by distinct comparison group rather than by collection entry or screen view. For example, 240 groups refreshed daily for a 30-day period, with a budget of two successful search pages per refresh, allow up to 14,400 search units before item enrichment. The number of collectors viewing those saved summaries does not enter that arithmetic.
Each additional successful search page or item lookup consumes a unit, including authenticated cache hits and successful empty pages. Failed requests consume zero units. Reusing a stored summary inside your app avoids making another API request; repeatedly calling SoldFetch's cache still uses units. Preserve the original observation time whenever you reuse evidence.
Coordinate refresh workers and interactive requests under the shared workspace limits. Keep an incomplete refresh separate from the last complete snapshot. If the API is temporarily unavailable, show the last snapshot with its age or withhold the estimate according to your freshness policy. The reliable pipeline guide covers queues and retries.
Use the current pricing catalog and dashboard Billing to choose an allowance and throughput limits. Self-service plans have hard usage caps and no automatic overages. Contractual uptime or support commitments require a signed enterprise agreement, as described in Terms section 11.2.
Run the example and prepare a small pilot
Download the complete offline Python example and run it with Python 3:
python3 collectibles-valuation-app.py
It uses only the standard library, performs no network requests, and prints the USD 42 summary. Checks cover duplicate listings, another comparison group, a range price, invalid amounts, incompatible currency, stale evidence, and an insufficient sample. It also carries the observation window and price limitations into the returned summary.
Start a pilot with one category and a small collection. Inspect rejected candidates, measure successful request usage, and verify that opening an item repeatedly serves the stored summary. Exercise missing evidence and failed refreshes before adding more categories.
For related product workflows, see the trade-in quote tool, marketplace price suggestions, and inventory pricing dashboard. Each uses reviewed observations to support a different application decision.
