# TCGplayer Pokemon Price & Stock Watchlist (`jpmarketdata/tcgplayer-english-pokemon-offer-shortlist`) Actor

Monitor up to 25 exact English Pokemon variants: condition-specific asking offers, available stock, disclosed US shipping and before-tax cost targets. Stable snapshot keys support scheduled price and inventory workflows.

- **URL**: https://apify.com/jpmarketdata/tcgplayer-english-pokemon-offer-shortlist.md
- **Developed by:** [h ichi](https://apify.com/jpmarketdata) (community)
- **Categories:** E-commerce, Automation
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$2.00 / 1,000 variant price and stock snapshot delivereds

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## TCGplayer Pokemon Price & Stock Watchlist

Monitor current asking offers for up to **25 exact English Pokemon card variants**. Choose each card's printing and condition, inspect available stock and one-card price plus disclosed US shipping, and optionally screen a before-tax cost target. Stable variant and listing IDs let a store or collector save repeated snapshots for repricing and procurement workflows.

### Input

Supply exactly one of `productIds` or `watchlist`. `productIds` accepts 1–25 positive numeric TCGplayer Pokemon single-card product IDs and uses the common `printing` and `condition`. The compatible defaults remain Holofoil and Near Mint. `watchlist` accepts 1–25 objects with `productId` plus optional per-card `printing`, `condition` and `maxKnownSubtotalUsd`. Conditions are Near Mint, Lightly Played, Moderately Played, Heavily Played and Damaged; printings are Normal, Holofoil and Reverse Holofoil. These are TCGplayer labels, not grading certificates or equivalence to another marketplace.

```json
{"watchlist":[{"productId":517044,"printing":"Holofoil","condition":"Near Mint","maxKnownSubtotalUsd":95},{"productId":517045,"printing":"Holofoil","condition":"Lightly Played","maxKnownSubtotalUsd":300}],"maxOffers":5}
```

The IDs identify Venusaur ex 198/165 and Charizard ex 199/165 from Scarlet & Violet 151. Product IDs are not seller, listing or SKU IDs. `maxOffers` returns 1–20 nested offers per variant from the first 50 source offers sorted by price plus shipping. English, standard ungraded singles, one priced card and a US destination are fixed. Unknown fields and arbitrary URLs are rejected. Duplicate product/printing/condition targets are acquired and billed once; duplicates with conflicting cost targets fail before requests.

### Output and repeated use

One `english_pokemon_procurement_screen` row per distinct variant contains `watchKey`, exact card/set/number identity, requested condition and printing, original listing IDs, in-stock quantities, asking prices, explicit shipping, known one-card subtotals, sample counts, exclusions and observation time. The default view shows variant, condition, lowest observed cost, qualified sampled stock and the optional cost-target result.

Schedule the same watchlist and archive rows keyed by `watchKey` and `checkedAt` to compare observations. Listing IDs identify the same observed offer across runs. The Actor does not maintain a historical database, send alerts or infer that an offer omitted from its bounded sample was sold. Seller names, addresses and seller IDs/keys, descriptions, pictures and custom listings are discarded.

`minimumObservedKnownSubtotalUsd` is the lowest **qualified observed** one-card subtotal before tax. `availableQuantityInQualifiedSample` sums units across qualified sampled offers, including offers omitted by `maxOffers`; it is not total marketplace stock. `observedOfferMeetsTarget` screens only observed qualified offers against the user's cost ceiling. Missing offers return null; false is not proof that no qualifying offer exists outside the sample. Source totals, sampled/qualified/returned counts and truncation flags expose that distinction.

Shipping is the public website's US empty-cart quote; combining multiple cards or sellers can change shipping. Tax, checkout adjustments, confirmed bookability and source price-update time remain unknown. `checkedAt` records acquisition, not a verified price-update time. Prices are asking offers, not sales or market-price estimates. No European comparison or worldwide-delivery capability is claimed.

A properly parsed explicit zero or a sample with no qualified offer returns `no_qualifying_offers`, a null minimum and an explicit reason. This is observed procurement evidence, not entire-market sold out. Authentication, blocks, rate limits, malformed responses or failure of any requested source acquisition fail before dataset delivery or charging.

### Charging and limits

Price: **$0.002 per distinct product/printing/condition snapshot delivered** ($2 per 1,000 snapshots). Up to 25 variants costs $0.05 in Actor events. Each complete snapshot, including explicit negative evidence, uses the sole `procurement-screen-created` event. Nested offers, cost-target checks and duplicates add no events. No actor-specific free trial is promised; platform credits may apply.

HTTP only, 256 MB, no required third-party API or paid dependency. At most 52 requests: two fresh robots checks, one product detail per distinct ID and one listing search per variant. Requests to the same origin are spaced at least ten seconds apart, respecting the observed crawl delay; 25 variants can therefore take about nine minutes with responsive sources. Each body is capped at 2 MiB, each request at 30 seconds, and the run at 900 seconds. There are no retries, proxies, login, cart mutations or transactions. Increased source crawl delay fails for review rather than being ignored. Validate the full watchlist and event allowance before I/O; acquire all variants before delivering any row.

### Privacy and source terms

Only public product and necessary offer facts are returned. Requests reproduce the public website's read-only listing search without developer keys or account cookies. TCGplayer's terms restrict scraping and commercial combination/distribution; DR-0007 accepts grey contractual risk without asserting permission. Exact terms and current access evidence are in the dated scout. Cardmarket remains excluded while its access/robots requirements are unresolved.

Source availability can change between runs. A source failure is reported as an error before any row or event is delivered.

# Actor input Schema

## `productIds` (type: `array`):

One to twenty-five exact Pokemon single-card product IDs. Uses the common printing/condition. Use productIds or watchlist, never both; duplicate variants count once.

## `printing` (type: `string`):

Default exact source printing, overridable per watchlist target. English and public US one-card shipping remain fixed.

## `maxOffers` (type: `integer`):

Return 1–20 qualified offers from a source sample capped at 50. Default 5; detail count does not add billable events.

## `condition` (type: `string`):

Exact TCGplayer source condition; overridable per watchlist target. No equivalence to grading or other marketplaces.

## `watchlist` (type: `array`):

Instead of productIds, supply 1–25 objects with productId and optional printing, condition and maxKnownSubtotalUsd. Cost targets compare one-card asking price plus disclosed US shipping before tax. Duplicate variants with conflicting targets are rejected.

## Actor input object example

```json
{
  "productIds": [
    517044
  ],
  "printing": "Holofoil",
  "maxOffers": 5,
  "condition": "Near Mint"
}
```

# Actor output Schema

## `results` (type: `string`):

Condition-specific offers, available sampled units, disclosed US shipping, and optional before-tax cost targets.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "productIds": [
        517044
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("jpmarketdata/tcgplayer-english-pokemon-offer-shortlist").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "productIds": [517044] }

# Run the Actor and wait for it to finish
run = client.actor("jpmarketdata/tcgplayer-english-pokemon-offer-shortlist").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "productIds": [
    517044
  ]
}' |
apify call jpmarketdata/tcgplayer-english-pokemon-offer-shortlist --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,jpmarketdata/tcgplayer-english-pokemon-offer-shortlist"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/X0hKA0thDN1kpR4Gl/builds/QGtiMYxevQKZdb34Z/openapi.json