---
title: "Get Sales Trends by Category (Matched Sales Only)"
method: POST
path: "/v1/cards/sales-stats-by-category"
tags: ["Market Data"]
---

# Get Sales Trends by Category (Matched Sales Only)

`POST /v1/cards/sales-stats-by-category`

## Request

- Base URL: `https://api.cardhedger.com`
- URL: `https://api.cardhedger.com/v1/cards/sales-stats-by-category`
- Auth: API key in header `X-API-Key`

**Matched sales only.** A matched sale is a sale Card Hedge has linked
to a specific card in its catalog. This endpoint includes only matched sales
whose linked card has a known category. **Unmatched sales are excluded from
every count, total amount, and average price.** These statistics do not
represent all marketplace sales in a category.

Return daily, weekly, or monthly sale counts, total amounts (USD), and average
sale prices grouped by the linked card's category. Category names match
exactly, ignoring case and surrounding whitespace. A category word appearing
in a sale title does not qualify that sale for inclusion.

A zero count means no qualifying matched sales were found for the category
and period; it does not mean no marketplace sales occurred. Unknown categories
also return zero statistics.

Like sales-stats-by-player, buckets are UTC calendar days, ISO weeks
(Monday–Sunday), or months, ordered oldest to newest. `periods` includes
the current partial bucket when `include_current` is true. The response's
`scope: matched_only` distinguishes these statistics from all-market sales.

Completed buckets are cached for **24 hours**; the current partial bucket
for **5 minutes**. Day and period boundaries use separate cache keys.
Results reflect indexed card links and may lag changes by the cache TTL.
Redis failures fall back to querying OpenSearch. Limits: 25 categories,
day ≤ 90 / week ≤ 52 / month ≤ 24 periods, and 150 total buckets.

## Request body

- SalesStatsByCategoryRequest
  - `categories` string[], required: Exact linked-card category names (case-insensitive), in response order (max 25). Only matched sales with a known card category are counted.
  - `interval` 'day' | 'week' | 'month': UTC calendar buckets: day, ISO week (Monday–Sunday), or month.
  - `periods` integer: Buckets per category, including the current period when requested. Caps: day ≤ 90, week ≤ 52, month ≤ 24; categories × periods ≤ 150.
  - `include_current` boolean: Include the in-progress period as the newest, partial bucket.

## Response `200`

Successful Response

- SalesStatsByCategoryResponse
  - `scope` 'matched_only': Always matched_only: includes only sales Card Hedge has linked to catalog cards with a known category. Unmatched sales are excluded from all statistics; these are not all-marketplace totals.
  - `interval` 'day' | 'week' | 'month', required
  - `periods` integer, required: Number of buckets returned per category.
  - `results` CategorySalesStats[], required: One entry per requested category, in request order.
    - `category` string, required: Requested category name.
    - `buckets` CategorySalesStatsBucket[], required: Sales buckets ordered oldest to newest, with empty periods filled.
      - `start` string, required: Bucket start date in UTC, inclusive (YYYY-MM-DD).
      - `end` string, required: Bucket end date in UTC, inclusive (YYYY-MM-DD). For a partial bucket this is today's date.
      - `count` integer, required: Number of matched sales whose linked card belongs to this category. Unmatched sales are excluded; zero does not imply no marketplace sales.
      - `total_amount` number, required: Total price in USD of included matched sales only.
      - `average_sale` number, required: Mean price in USD of included matched sales only; 0 for empty buckets.
      - `partial` boolean: True only for the in-progress current bucket. Always false for fully-closed historical buckets.

## Other responses

- `422`: Invalid category list, interval, or bucket budget.
- `502`: Price-history search service failed.
- `503`: Category stats are not enabled or configured.

## Changes

- **2026-09-23** `7854fa0dda28`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/cardhedger/apis/card-hedge-api/changes/v1/cards/sales-stats-by-category/post.md)

---

[API](https://skmtc.dev/cardhedger/apis/card-hedge-api.md) - [All operations](https://skmtc.dev/cardhedger/apis/card-hedge-api/llms.txt) - [OpenAPI document](https://skmtc.dev/cardhedger/apis/card-hedge-api/revisions/6de42f192a4d?raw)