Players

List a player's buy orders

Every buy order one player has open right now.

GET/v1/players/{username}/orders

Returns the player's open buy orders, including ones that have received everything and are waiting to be collected. With the default refresh=auto, a player whose orders are more than 5 minutes old is checked again before the API answers.

Orders are also refreshed after each live lookup of the player's profile. Check player.orders.checkedAt on the profile to see when.

Authentication

API key with the read scope

Cached for

20 s

Data updates

Checked again on request when older than 5 minutes, and after live lookups.

curl "https://api.donutstats.io/v1/players/Wampiptiii01/orders?limit=2&refresh=none" \
  -H "x-api-key: $DONUTSTATS_API_KEY"

Response200OK

{
  "page": 1,
  "limit": 2,
  "total": 4,
  "updatedAt": 1792776644278,
  "entries": [
    {
      "id": 4434964,
      "product": {
        "key": "ancient_debris",
        "item": "ancient_debris",
        "name": "Ancient Debris",
        "variant": "",
        "category": "valuables",
        "details": null
      },
      "unitPrice": 1,
      "amount": 100000,
      "delivered": 0,
      "remaining": 100000,
      "firstSeenAt": 1792769116939,
      "lastSeenAt": 1792776643378,
      "progressedAt": null,
      "marketPrice": 4200000,
      "buyer": "Wampiptiii01"
    },
    {
      "id": 4431676,
      "product": {
        "key": "gilded_blackstone",
        "item": "gilded_blackstone",
        "name": "Gilded Blackstone",
        "variant": "",
        "category": "valuables",
        "details": null
      },
      "unitPrice": 1,
      "amount": 100000,
      "delivered": 2,
      "remaining": 99998,
      "firstSeenAt": 1792769116939,
      "lastSeenAt": 1792776643378,
      "progressedAt": null,
      "marketPrice": 4500000,
      "buyer": "Wampiptiii01"
    }
  ],
  "scan": {
    "status": "skipped",
    "checkedAt": 1792776643378
  }
}

Try itCounts towards your plan

Checks share the lookup budget

A check started by refresh=auto counts against the same per minute budget as live player lookups. Past it you get stored data with scan.status: rate_limited. Use refresh=none for bulk reads.

Path parameters

usernamestringrequired
Minecraft username, case insensitive. 1 to 16 letters, digits or underscores, with an optional leading dot for Bedrock players.

Query parameters

sortstringoptionaldefault value
value: most money left to pay out first. price: best price per item first. newest: most recently placed first. amount: most items wanted first.
valuepricenewestamount
refreshstringoptionaldefault auto
auto: if this player's data is more than 5 minutes old, check it again and wait up to 15 seconds for the result. none: return stored data only, never wait.
autonone
pageintegeroptionaldefault 1
Page to return, starting at 1.
1 to 100,000
limitintegeroptionaldefault 50
Entries per page.
1 to 100

Response

A page of orders, each with buyer set, plus what the check did.

pageinteger
The page you asked for, starting at 1.
limitinteger
Entries per page.
totalinteger
Entries across every page that match your filters.
updatedAttimestamp | null
When the underlying data last changed. null where it does not apply.
entriesOrder[]
The entries on this page.
ShowHide11 child fields
- idinteger
  Stable id of the buy order.
- productProduct
  What the order wants to buy.
  ShowHide6 child fields
  - keystring
    Unique product key: the item id, plus the variant in square brackets when there is one. Examples: diamond, elytra[mending,unbreaking:3], potion[poison]. Use it with product= filters and /v1/items/{key}.
  - itemstring
    Minecraft item id without the minecraft: namespace, for example netherite_sword. Many products can share one item id.
  - namestring
    Display name, for example Potion of Poison.
  - variantstring
    What sets this product apart from the plain item. Empty for plain items. See variants for the rules.
  - categorystring | null
    One of combat, tools, valuables, drops, food, potions, blocks or misc.
  - detailsProductDetails | null
    Structured extras such as enchantments, shulker box contents or a custom name.
    ShowHide5 child fields
    enchantmentsEnchantment[]
    Enchantments on the item itself, sorted by id. Left out when there are none.
    storedEnchantmentsEnchantment[]
    Enchantments stored in an enchanted book. Left out for every other item.
    contentsContainerEntry[]
    What a shulker box holds, one entry per item id with counts added together, largest first.
    customNamestring
    The name shown in game when it differs from the default item name. DonutSMP renames some items, for example Dried Ghast on a skeleton skull.
    flightDurationinteger
    Flight duration of a firework rocket, from 1 to 3.
- unitPricenumber
  What the order pays per item delivered.
- amountinteger
  Total number of items the order asks for.
- deliveredinteger
  Items delivered so far.
- remaininginteger
  Items still wanted: amount minus delivered.
- firstSeenAttimestamp
  When the order first appeared.
- lastSeenAttimestamp
  When the order was last confirmed open.
- progressedAttimestamp | null
  When a delivery to this order was last recorded. null if none yet.
- marketPricenumber | null
  Current market price of the product.
- buyerstring | null
  Username of the player who placed the order, once known. null until then.
scanLookup
What this request did: fresh when the stored data was recent enough, updated after checking again, pending when the check is still running, or rate_limited, unavailable or skipped. checkedAt is when this player's data was last refreshed.
ShowHide2 child fields
- statusstring
  One of fresh, updated, not_found, pending, rate_limited, unavailable or skipped. See live lookups.
- checkedAttimestamp | null
  When the stats you got were last refreshed.

Status codes

Status	When
400Bad Request	The username is not valid.
404Not Found	The player is not on record.