> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cromos.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Events

> What each event means, when it fires, and the records it carries.

Names are `<game>.<entity>.<action>`. The `pokemon.` prefix leaves room for another game without
renaming anything you have already built against.

Every record shape below is the **same shape `/v1` already serves** for that entity. A card in
`pokemon.cards.updated` is exactly what `GET /v1/cards/{id}` returns inside its `data`, and so
on, so one decoder covers both.

A delivery carries these records directly. The `{ data, error }` envelope belongs to a `/v1`
read, not to a delivery, and nothing below is wrapped in it.

A group that changed more than 500 records in one run arrives split across several deliveries,
each carrying a `chunk: { index, of }` field alongside the records. See
[the delivery body](/webhooks/overview#the-delivery-body). A smaller group carries no `chunk`
key at all.

## Cards

### `pokemon.cards.updated`

**Card details changed.** A new card appeared, or an existing one's name, rarity, illustrator,
category, metadata or variants changed.

```json theme={null}
{
  "id": "evt_2f8a1c9b4e7d4a3f8c1b6e2d9a0f4c7b",
  "name": "pokemon.cards.updated",
  "created_at": "2026-07-31T03:58:41.006Z",
  "data": {
    "cards": [
      {
        "id": "sv08-238",
        "expansion_id": "sv08",
        "number": "238",
        "name": "Pikachu ex",
        "rarity": "Special illustration rare",
        "illustrator": "GIDORA",
        "image": {
          "low": "https://assets.cromos.so/cards/sv08-238/low.webp",
          "high": "https://assets.cromos.so/cards/sv08-238/high.webp"
        },
        "category": "Pokemon",
        "metadata": {
          "hp": 200,
          "types": ["Lightning"],
          "pokedex_numbers": [25],
          "stage": "Basic",
          "evolve_from": null,
          "description": null,
          "effect": null,
          "trainer_type": null,
          "energy_type": null,
          "retreat": 1,
          "abilities": [
            {
              "kind": "ability",
              "name": "Resolute Heart",
              "text": "If this Pokémon has full HP and would be Knocked Out by damage from an attack, it is not Knocked Out, and its remaining HP becomes 10."
            }
          ],
          "attacks": [
            {
              "name": "Topaz Bolt",
              "cost": ["Grass", "Lightning", "Metal"],
              "damage": "300",
              "text": "Discard 3 Energy from this Pokémon."
            }
          ],
          "weaknesses": [{ "type": "Fighting", "modifier": "x2" }],
          "resistances": null,
          "legality": { "expanded": true, "standard": true }
        },
        "variants": [
          {
            "id": 29178,
            "type": "holo",
            "subtype": null,
            "size": "standard",
            "stamps": [],
            "foil": null,
            "tcgplayer": [
              {
                "condition": "NM",
                "currency": "USD",
                "market": 32497,
                "low": 28899,
                "high": 42599,
                "listing_count": 22,
                "observed_on": "2026-07-31"
              },
              {
                "condition": "LP",
                "currency": "USD",
                "market": 27591,
                "low": 23304,
                "high": 32190,
                "listing_count": 15,
                "observed_on": "2026-07-31"
              },
              {
                "condition": "MP",
                "currency": "USD",
                "market": 22000,
                "low": 22000,
                "high": 22000,
                "listing_count": 6,
                "observed_on": "2026-07-31"
              },
              {
                "condition": "HP",
                "currency": "USD",
                "market": 22499,
                "low": 22499,
                "high": 22499,
                "listing_count": 3,
                "observed_on": "2026-07-31"
              },
              {
                "condition": "DMG",
                "currency": "USD",
                "market": 21894,
                "low": 21500,
                "high": 22681,
                "listing_count": 1,
                "observed_on": "2026-07-31"
              }
            ]
          }
        ]
      }
    ]
  }
}
```

### `pokemon.cards.deleted`

**A card was removed.** Nothing emits this event today. It stays in the catalogue so a mirror
already knows how to handle a card deletion the day one becomes possible, rather than that being
a docs change, a console change and your own deploy all at once.

```json theme={null}
{
  "id": "evt_4c1a7f9b2e6d3a8f1c5b9e2d4a7f8c3b",
  "name": "pokemon.cards.deleted",
  "created_at": "2026-07-31T03:58:41.006Z",
  "data": { "card_ids": ["sv08-999"] }
}
```

## Card variants

### `pokemon.card_variants.deleted`

**A card printing was removed.** One or more printings no longer exist. Each entry names the
`card_id` the printing belonged to alongside `variant_id`, that printing's own numeric id and
the same value `GET /v1/cards/{id}`'s `variants[].id` carries. The card itself is not necessarily
deleted, only that printing of it, and two entries can name different cards in one delivery.

```json theme={null}
{
  "id": "evt_9a3f6c1e8d2b4a7f9c1e6d3a8f2b5c7d",
  "name": "pokemon.card_variants.deleted",
  "created_at": "2026-07-31T03:58:41.006Z",
  "data": {
    "variants": [
      { "card_id": "bog-4", "variant_id": 48212 },
      { "card_id": "sv08-125", "variant_id": 48214 }
    ]
  }
}
```

## Card prices

### `pokemon.card_prices.snapshot`

**Daily card prices published.** Card prices rewrite most of their rows every day, so this is not
a record of what changed -- it is a pointer to a published file holding every current card price.
`data.currency` is always `"USD"`. Fetch `url`, verify the download against `sha256`, and read
prices from the file itself; nothing about an individual card's price rides on the event.

```json theme={null}
{
  "id": "evt_7b3e9d1a2c4f4b8e9a6d3c1f5b2e8a4d",
  "name": "pokemon.card_prices.snapshot",
  "created_at": "2026-08-05T03:30:11.184Z",
  "data": {
    "currency": "USD",
    "snapshot": [
      {
        "snapshot_date": "2026-08-05",
        "rows": 139577,
        "subjects": 19295,
        "url": "https://assets.cromos.so/prices/cards/2026-08-05.c3f8a1e9b2d4f7a1c8e3b6d9f2a4c7e1b8d3f6a9c2e5b8d1f4a7c3e6b9d2f5a8.ndjson.gz",
        "sha256": "c3f8a1e9b2d4f7a1c8e3b6d9f2a4c7e1b8d3f6a9c2e5b8d1f4a7c3e6b9d2f5a8",
        "bytes": 1583488
      }
    ]
  }
}
```

`rows` counts price rows in the file; `subjects` counts the distinct cards represented, always
fewer since one card carries several rows.

## Sealed products

### `pokemon.products.updated`

**Sealed product details changed.** A booster box, ETB, collection or similar changed: its name,
number, image, the expansions it belongs to, or its current prices.

```json theme={null}
{
  "id": "evt_5a2f7c1e8d3b4a9f6c2e1d8b3a7f4c9e",
  "name": "pokemon.products.updated",
  "created_at": "2026-07-31T03:59:12.301Z",
  "data": {
    "products": [
      {
        "id": 476452,
        "name": "Scarlet & Violet Booster Box",
        "clean_name": "Scarlet and Violet Booster Box",
        "number": null,
        "image": {
          "low": "https://assets.cromos.so/products/476452/low.webp",
          "high": "https://assets.cromos.so/products/476452/high.webp"
        },
        "tcgplayer_url": "https://www.tcgplayer.com/product/476452/pokemon-sv01-scarlet-and-violet-base-set-scarlet-and-violet-booster-box",
        "expansions": [{ "id": "sv01", "name": "Scarlet & Violet" }],
        "tcgplayer": [
          {
            "condition": "NM",
            "variant": "Normal",
            "currency": "USD",
            "market": 31101,
            "low": 29999,
            "high": 31698,
            "listing_count": 19,
            "observed_on": "2026-07-31"
          }
        ]
      }
    ]
  }
}
```

### `pokemon.products.removed`

**A sealed product was removed.** It left the catalogue, or was detached from every expansion it
was listed under. `product_ids` are those products' own numeric ids.

```json theme={null}
{
  "id": "evt_1e4b7a2f9c6d3e8a1b4f7c2e9a6d3b8f",
  "name": "pokemon.products.removed",
  "created_at": "2026-07-31T03:59:12.301Z",
  "data": { "product_ids": [476452, 502001] }
}
```

## Sealed product prices

### `pokemon.product_prices.snapshot`

**Daily sealed product prices published.** The same pointer shape as `card_prices.snapshot`,
naming a published file of current sealed product prices instead of card prices.

```json theme={null}
{
  "id": "evt_8c2f5a1e7d4b3a9f6c1e8d2b5a7f4c9e",
  "name": "pokemon.product_prices.snapshot",
  "created_at": "2026-08-05T03:30:47.552Z",
  "data": {
    "currency": "USD",
    "snapshot": [
      {
        "snapshot_date": "2026-08-05",
        "rows": 4128,
        "subjects": 612,
        "url": "https://assets.cromos.so/prices/products/2026-08-05.a7e2c9f4b1d8e3a6c9f2b5d8e1a4c7f0b3d6e9a2c5f8b1d4e7a0c3f6b9d2e5a8.ndjson.gz",
        "sha256": "a7e2c9f4b1d8e3a6c9f2b5d8e1a4c7f0b3d6e9a2c5f8b1d4e7a0c3f6b9d2e5a8",
        "bytes": 84213
      }
    ]
  }
}
```

## Expansions

### `pokemon.expansions.created`

**A new expansion appeared.** It usually arrives sparse, named and dated, with cards landing
over the following days. Treat it as "start watching", not "fetch everything now".

```json theme={null}
{
  "id": "evt_3c9f2b8e1d4a7c5f9b3e2a6d1c8f4b7e",
  "name": "pokemon.expansions.created",
  "created_at": "2026-07-31T03:57:02.884Z",
  "data": {
    "expansions": [
      {
        "id": "sv10",
        "series_id": "sv",
        "name": "Destined Rivals",
        "logo": {
          "low": "https://assets.cromos.so/expansions/sv10/logo/low.webp",
          "high": "https://assets.cromos.so/expansions/sv10/logo/high.webp"
        },
        "symbol": "https://assets.cromos.so/expansions/sv10/symbol/image.webp",
        "palette": ["#f4c542", "#1f3a5f", "#c0392b", "#2c2c2c"],
        "release_date": "2025-05-30",
        "card_count_total": 244,
        "card_count_official": 182,
        "legal_standard": false,
        "legal_expanded": true
      }
    ]
  }
}
```

### `pokemon.expansions.updated`

**Expansion details changed.** An expansion's own name, series, logo, symbol or legality was
corrected. Nothing about its cards or prices changes here. Those arrive as their own events.

```json theme={null}
{
  "id": "evt_5d2a9f1c7b4e8a3f6c1d9b2e4a7f8c3d",
  "name": "pokemon.expansions.updated",
  "created_at": "2026-07-31T03:57:02.884Z",
  "data": {
    "expansions": [
      {
        "id": "sv08",
        "series_id": "sv",
        "name": "Surging Sparks",
        "logo": {
          "low": "https://assets.cromos.so/expansions/sv08/logo/low.webp",
          "high": "https://assets.cromos.so/expansions/sv08/logo/high.webp"
        },
        "symbol": null,
        "palette": ["#1a1a2e", "#e94560", "#0f3460", "#16213e"],
        "release_date": "2024-11-08",
        "card_count_total": 252,
        "card_count_official": 191,
        "legal_standard": false,
        "legal_expanded": true
      }
    ]
  }
}
```

## Series

### `pokemon.series.created`

**A new series appeared.**

The `sv` series carries 19 expansions. Trimmed to the first three below, still in release-date
order, to keep the example short.

```json theme={null}
{
  "id": "evt_8f1e4c7a3b9d2e6f1a4c8b3e7d2a9f5c",
  "name": "pokemon.series.created",
  "created_at": "2026-07-31T03:56:18.442Z",
  "data": {
    "series": [
      {
        "id": "sv",
        "name": "Scarlet & Violet",
        "logo": {
          "low": "https://assets.cromos.so/series/sv/logo/low.webp",
          "high": "https://assets.cromos.so/series/sv/logo/high.webp"
        },
        "palette": ["#d0392b", "#2d2d54", "#f2b134", "#3a6b96"],
        "expansions": [
          {
            "id": "sv01",
            "name": "Scarlet & Violet",
            "logo": {
              "low": "https://assets.cromos.so/series/sv/logo/low.webp",
              "high": "https://assets.cromos.so/series/sv/logo/high.webp"
            },
            "symbol": "https://assets.cromos.so/expansions/sv01/symbol/image.webp",
            "palette": ["#d0392b", "#2d2d54", "#f2b134", "#3a6b96"],
            "release_date": "2023-03-31",
            "card_count_total": 258
          },
          {
            "id": "sve",
            "name": "Scarlet & Violet Energy",
            "logo": null,
            "symbol": null,
            "palette": null,
            "release_date": "2023-03-31",
            "card_count_total": 24
          },
          {
            "id": "svp",
            "name": "SVP Black Star Promos",
            "logo": null,
            "symbol": null,
            "palette": null,
            "release_date": "2023-03-31",
            "card_count_total": 226
          }
        ]
      }
    ]
  }
}
```

### `pokemon.series.updated`

**Series details changed.** A series' own name or logo was corrected.

Trimmed the same way as above: the first three of `sv`'s 19 expansions, in release-date order.

```json theme={null}
{
  "id": "evt_6b9d2a7f4c1e8b3a6d9f2c5e8b1a4d7f",
  "name": "pokemon.series.updated",
  "created_at": "2026-07-31T03:56:18.442Z",
  "data": {
    "series": [
      {
        "id": "sv",
        "name": "Scarlet & Violet",
        "logo": {
          "low": "https://assets.cromos.so/series/sv/logo/low.webp",
          "high": "https://assets.cromos.so/series/sv/logo/high.webp"
        },
        "palette": ["#d0392b", "#2d2d54", "#f2b134", "#3a6b96"],
        "expansions": [
          {
            "id": "sv01",
            "name": "Scarlet & Violet",
            "logo": {
              "low": "https://assets.cromos.so/series/sv/logo/low.webp",
              "high": "https://assets.cromos.so/series/sv/logo/high.webp"
            },
            "symbol": "https://assets.cromos.so/expansions/sv01/symbol/image.webp",
            "palette": ["#d0392b", "#2d2d54", "#f2b134", "#3a6b96"],
            "release_date": "2023-03-31",
            "card_count_total": 258
          },
          {
            "id": "sve",
            "name": "Scarlet & Violet Energy",
            "logo": null,
            "symbol": null,
            "palette": null,
            "release_date": "2023-03-31",
            "card_count_total": 24
          },
          {
            "id": "svp",
            "name": "SVP Black Star Promos",
            "logo": null,
            "symbol": null,
            "palette": null,
            "release_date": "2023-03-31",
            "card_count_total": 226
          }
        ]
      }
    ]
  }
}
```