Read buy boosts

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

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

{
  "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.

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.

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.