---
title: Read buy boosts
description: How landing pages and X posting apps read a shop's buy boosts (boosted price, how many are left, dates).
---

Buy boosts are the cards and BOXes a shop is buying above its usual price for a while. The shop reviews prices and quantities in the console every day, and recording acceptance of a final quote lowers the number left ([buy boosts guide](/en/guides/purchase/purchase-boosts)). External apps read the list over the API and show it on landing pages and posts.

## Required scope

`purchase-boosts:read` is all you need; no inventory scope (`inventory:read`) is required. Ask the shop to allow "Read buy boosts" when registering your app, and include `purchase-boosts:read` in `scope` when authorizing.

## Read the list

```bash
curl https://api.toreca-cloud.com/partner/v1/purchase-boosts \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

```json
{
  "boosts": [
    {
      "id": "01a1…",
      "target": {
        "kind": "card",
        "card": {
          "id": "01a0…",
          "name": "リザードンex",
          "cardNumber": "201/165",
          "imageUrl": "https://images.toreca-cloud.com/…",
          "rarity": { "code": "SAR", "name": "SAR" },
          "set": { "id": "…", "code": "SV2a", "name": "ポケモンカード151" },
          "game": {
            "id": "…",
            "code": "pokemon",
            "name": "ポケモンカードゲーム"
          }
        },
        "grade": {
          "id": "…",
          "code": "10",
          "label": "PSA 10",
          "serviceCode": "psa",
          "serviceName": "PSA",
          "serviceKind": "third_party"
        }
      },
      "priceMinor": 120000,
      "currency": "JPY",
      "remainingQuantity": 2,
      "status": "open",
      "startsAt": null,
      "endsAt": "2026-10-10T15:00:00.000Z",
      "note": "美品に限ります",
      "updatedAt": "2026-10-04T09:12:33.000Z"
    }
  ],
  "generatedAt": "2026-10-04T09:30:00.000Z"
}
```

| Field                 | Meaning                                                                             |
| --------------------- | ----------------------------------------------------------------------------------- |
| `target.kind`         | `card`, or `box` for a BOX, pack or deck. A BOX has its details in `target.product` |
| `target.grade`        | The grade. `null` means any grade                                                   |
| `priceMinor`          | Boosted price per piece, in whole yen (120000 is ¥120,000)                          |
| `remainingQuantity`   | How many more the shop will buy. `null` means no limit                              |
| `startsAt` / `endsAt` | The dates. The boost closes at the `endsAt` instant. `null` means not set           |
| `note`                | A line the shop wrote for landing pages and posts                                   |

The list holds only boosts open right now, highest price first. Boosts that haven't started, are paused, ended or expired are left out.

## Include closed boosts

Add `include=filled` to also get boosts with none left, as `status: "filled"`. Use it to show "closed" on a landing page.

```bash
curl "https://api.toreca-cloud.com/partner/v1/purchase-boosts?include=filled" \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Tips

- The number left drops with every purchase. Refresh the list every few minutes (up to 15), or fetch it server-side on each view. Don't cache responses.
- Build post text from `target.card.name`, the grade `label`, `priceMinor` and `remainingQuantity`.
- Use `imageUrl` as is. Cards without an image have `null`.
- When the shop stops a boost, it disappears from the next response. Don't keep showing the previous result.

```ts
const yen = new Intl.NumberFormat("ja-JP");
const lines = boosts.map((boost) => {
  const name =
    boost.target.kind === "card"
      ? `${boost.target.card.name}${boost.target.grade ? ` ${boost.target.grade.label}` : ""}`
      : boost.target.product.name;
  const left =
    boost.remainingQuantity === null
      ? ""
      : ` (${boost.remainingQuantity} left)`;
  return `${name} ¥${yen.format(boost.priceMinor)}${left}`;
});
const post = ["Today's buy boosts", ...lines].join("\n");
```

Field definitions are in the [API reference](/en/api/reference).