---
title: "Subscribe Cards to Price Tracking"
method: POST
path: "/v1/cards/subscribe-price-updates"
tags: ["Market Data"]
---

# Subscribe Cards to Price Tracking

`POST /v1/cards/subscribe-price-updates`

## Request

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

Enroll one or more card + grade combinations in CardHedge's price tracking.

Once subscribed, Card Hedge sends price changes to the webhook URL registered for your `client_id`. Before subscribing, provide Card Hedge with the public webhook URL that should receive these updates.

**Webhook delivery**

Your URL must accept an HTTP `POST` with an `application/json` body. For the first subscription in the request example, a price update is posted in this format:

```json
{
  "message_type": "price_update",
  "external_id": "test_123",
  "card_id": "1586812246197x228181943611293700",
  "grade": "PSA 10",
  "price": "45.00"
}
```

`external_id` echoes the reference supplied with the subscription so you can match the update to the correct record in your system. If you omit it, the CardHedge `card_id` is used.

**Requires a CardHedge Client ID** (`client_id`). Contact Card Hedge if you don't have one.

- **external_id** is your own reference for the subscription; defaults to the `card_id` when omitted.
- Up to 100 subscriptions per request, processed in parallel.
- Individual failures do not affect other subscriptions — the response always returns HTTP 200 with per-item success/failure status.

## Request body

- SubscribePriceUpdatesRequest: Request to subscribe to price updates for one or more cards.
  - `client_id` string, required: Your CardHedge client ID, used to authenticate with the price subscription service.
  - `subscriptions` PriceSubscriptionItem[], required: List of cards to subscribe to price updates (max 100)
    - `card_id` string, required: CardHedge card ID
    - `grade` string, required: Card grade (e.g., 'PSA 10', 'BGS 9.5')
    - `external_id` string, nullable: Optional external reference ID. If omitted, the card_id is used as the external identifier.

## Response `200`

Subscription results (always returned, even on partial failure)

- SubscribePriceUpdatesResponse: Response showing the outcome of each subscription attempt.
  - `results` SubscriptionResult[], required: Per-card subscription results
    - `card_id` string, required: CardHedge card ID from request
    - `grade` string, required: Grade from request
    - `external_id` string, required: External ID used (card_id if none was provided)
    - `success` boolean, required: Whether the subscription was created successfully
    - `error` string, nullable: Error message if subscription failed
  - `total_requested` integer, required: Number of subscriptions requested
  - `total_successful` integer, required: Number of subscriptions that succeeded

## Other responses

- `422`: Validation Error

---

[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)