---
title: "Get All Sales Trends (Daily/Weekly/Monthly)"
method: POST
path: "/v1/cards/sales-stats"
tags: ["Market Data"]
---

# Get All Sales Trends (Daily/Weekly/Monthly)

`POST /v1/cards/sales-stats`

## Request

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

Return **all indexed sales, including matched and unmatched sales**, using
the same calendar buckets and bucket fields as sales-stats-by-player, without
a player or category filter. Each bucket includes transaction `count`,
`total_amount` (USD), `average_sale` (USD), inclusive UTC `start`/`end` dates,
and `partial`. Totals describe Card Hedge's indexed sales coverage; a transaction
is one indexed sale record. Amounts are rounded to two decimals; indexed price
precision can produce small differences from source totals.

`interval` is day, week, or month (default week); `periods` defaults to 12.
Days use midnight-to-midnight UTC, ISO weeks run Monday–Sunday, and months
follow calendar boundaries. Caps match player trends: day ≤ 90, week ≤ 52,
month ≤ 24. Buckets run oldest to newest, with empty periods filled with zeros.

`include_current` defaults to false: the newest bucket ends yesterday UTC
(T-1), last Sunday, or the last day of the previous month. Explicitly set true
to include the in-progress period within the requested number of buckets.

Only completed buckets are cached, for **24 hours**. Partial buckets bypass
cache reads and writes. Late-arriving sales and corrections may take up to
the cache TTL to appear after indexing. Category labels are not required.

## Request body

- SalesStatsRequest
  - `interval` 'day' | 'week' | 'month': UTC calendar day, ISO week (Monday–Sunday), or calendar month.
  - `periods` integer: Number of buckets. Caps: day ≤ 90, week ≤ 52, month ≤ 24.
  - `include_current` boolean: Default false returns completed periods ending yesterday, last week, or last month. True includes the current uncached partial period within the requested number of buckets.

## Response `200`

Successful Response

- SalesStatsResponse
  - `scope` 'all_sales'
  - `currency` 'USD'
  - `interval` 'day' | 'week' | 'month', required
  - `periods` integer, required: Number of buckets returned.
  - `buckets` AllSalesStatsBucket[], required: Calendar buckets ordered oldest to newest, including empty periods.
    - `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 indexed sale records, including matched and unmatched sales.
    - `total_amount` number, required: Sum of indexed sale prices in USD, including unmatched sales.
    - `average_sale` number, required: Mean indexed sale price in USD; zero for an empty bucket.
    - `partial` boolean: True only for the in-progress current bucket. Always false for fully-closed historical buckets.

## Other responses

- `422`: Invalid interval, period count, or unsupported parameter.
- `502`: Price-history search service failed.
- `503`: Price-history search is 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/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)