Once Human Shop API

What the Once Human API covers

It covers the in-game shop's outfits, clothing, territory items and packs, with what is coming soon.

The shop resets every Wednesday at 22:00 UTC; the API has the new shop within minutes.

Each item comes with its name, type, price in Crystgin, rarity, pictures, how long it's on sale and a key that stays the same each time it's sold, so you can follow it across rotations.

Every rotation we've recorded is in the history endpoints, and each item's stays in the shop.

Quick start

Make a key (sign in with Discord, name your project, say what it does), set it as ITEMSHOP_API_KEY, then:

Today's Once Human shop:

curl -H "Authorization: Bearer $ITEMSHOP_API_KEY" \
  "https://itemshop.gg/api/v1/shop/once-human"

Every day it changed, then the shop on one of those days:

curl -H "Authorization: Bearer $ITEMSHOP_API_KEY" \
  "https://itemshop.gg/api/v1/history/once-human"

curl -H "Authorization: Bearer $ITEMSHOP_API_KEY" \
  "https://itemshop.gg/api/v1/history/once-human/YYYY-MM-DD"

One item and every time it has been in the shop, by the itemKey on it in a shop answer:

curl -H "Authorization: Bearer $ITEMSHOP_API_KEY" \
  "https://itemshop.gg/api/v1/items/once-human/oh:item:37540225"

Poll /api/v1/rotations to know when the shop changes, send back ETags, and show a “Data from itemshop.gg” link wherever you show the data.

A live answer

What /api/v1/shop/once-human returns for today's shop, cut to 2 of its 50 items:

{
  "data": {
    "game": "once-human",
    "shopDate": "2026-10-21",
    "updatedAt": "2026-10-27T11:17:00.709Z",
    "expiresAt": "2026-10-28T22:00:00.000Z",
    "stale": false,
    "itemCount": 50,
    "sections": [
      {
        "title": "Lightforge",
        "upcoming": false,
        "endsAt": null,
        "items": [
          {
            "id": "banner:56",
            "itemKey": null,
            "name": "Autumn Gleam",
            "type": "Lightforge banner · per draw",
            "rarity": null,
            "price": {
              "amount": 160,
              "label": null,
              "currency": "Crystgin",
              "currencyIcon": "https://itemshop.gg/currency/crystgin.webp",
              "regular": null
            },
            "images": {
              "card": "https://cdn.source.gs/once-human/img/shopping-cbt2-kongzhizi2-bg-279c42.webp",
              "render": null
            },
            "badge": null,
            "availability": {
              "from": "2026-09-28T23:00:00Z",
              "until": "2026-10-28T23:00:00Z",
              "untilLabel": null
            },
            "bundle": null,
            "contents": [
              {
                "name": "Windspeak Realm",
                "type": "Territory",
                "rarity": {
                  "name": "Epic",
                  "color": "#d29a2e"
                },
                "image": "https://cdn.source.gs/once-human/img/icon-gift-secretarea-503110.webp",
                "quantity": 1,
                "itemKey": null
              },
              {
                "name": "Hellfire Howl",
                "type": "Territory",
                "rarity": {
                  "name": "Epic",
                  "color": "#d29a2e"
                },
                "image": "https://cdn.source.gs/once-human/img/icon-coupe-gtr-a-02-2ad833.webp",
                "quantity": 1,
                "itemKey": null
              }
            ],
            "soldOut": false,
            "sourceUrl": null
          },
          {
            "id": "banner:57",
            "itemKey": null,
            "name": "Nevermore Protocol",
            "type": "Lightforge banner · per draw",
            "rarity": null,
            "price": {
              "amount": 160,
              "label": null,
              "currency": "Crystgin",
              "currencyIcon": "https://itemshop.gg/currency/crystgin.webp",
              "regular": null
            },
            "images": {
              "card": "https://cdn.source.gs/once-human/img/shopping-cbt2-tujiu2-bg-7091bd.webp",
              "render": null
            },
            "badge": null,
            "availability": {
              "from": "2026-10-08T09:00:00Z",
              "until": "2026-11-04T23:00:00Z",
              "untilLabel": null
            },
            "bundle": null,
            "contents": [
              {
                "name": "Zero-Bound Hub",
                "type": "Territory",
                "rarity": {
                  "name": "Epic",
                  "color": "#d29a2e"
                },
                "image": "https://cdn.source.gs/once-human/img/icon-gift-controlcenter-c376de.webp",
                "quantity": 1,
                "itemKey": null
              },
              {
                "name": "Dark Demon Hunter Set",
                "type": "Outfit",
                "rarity": {
                  "name": "Epic",
                  "color": "#d29a2e"
                },
                "image": "https://cdn.source.gs/once-human/img/icon-clothingset-m-set1101940-224-75feb2.webp",
                "quantity": 1,
                "itemKey": "oh:item:37540361"
              }
            ],
            "soldOut": false,
            "sourceUrl": null
          }
        ]
      }
    ]
  }
}

Every field is explained in the API docs.

Build it with an AI agent

Paste this into Claude Code, Cursor, Copilot or any coding agent in your project. It explains the API, keeps your key server-side and adds the link back.

Add itemshop.gg's Item Shop API to this project. Full reference: https://itemshop.gg/developers (read it if you can fetch pages).

The game I'm building for is Once Human (slug "once-human"): its shop is https://itemshop.gg/api/v1/shop/once-human.


Authentication
- Every request needs an API key, sent as the header "Authorization: Bearer <key>".
- Read the key from an environment variable named ITEMSHOP_API_KEY. Never hard-code it, commit it, or send it to a browser: call the API from server-side code only. If this project has an example env file, add ITEMSHOP_API_KEY to it with a placeholder.
- I make keys at https://itemshop.gg/account#api. If the variable isn't set, fail with a clear message saying so.

Endpoints (all GET, all JSON shaped { data, meta })
- https://itemshop.gg/api/v1/games: every game covered, with slug, name, page url, currency, reset time (UTC) and whether item history is available (itemHistory).
- https://itemshop.gg/api/v1/shop/{game}: the shop on sale now, as sections of items.
- https://itemshop.gg/api/v1/rotations: a fingerprint per game that changes when its shop changes. Poll this, and fetch a shop only when its fingerprint moves.
- https://itemshop.gg/api/v1/history/{game}: the days that game's shop changed, newest first.
- https://itemshop.gg/api/v1/history/{game}/{YYYY-MM-DD}: the shop on that day (UTC), same shape as /shop, plus shopDate and exact.
- https://itemshop.gg/api/v1/items/{game}/{itemKey}: one item and its stays in the shop. itemKey comes from items in shop or history answers.
Game slugs: valorant, marvel-rivals, overwatch, diablo-4, call-of-duty, rainbow-six-siege, aniimo, apex-legends, arc-raiders, battlefield-6, dead-by-daylight, war-thunder, pubg, once-human, league-of-legends, teamfight-tactics, path-of-exile-2, sea-of-thieves, wardogs, discord, rust.

The shop answer
- data: { game, shopDate, updatedAt, expiresAt, stale, itemCount, sections: [{ title, upcoming, endsAt, items }] }.
- Each item: { id, itemKey, name, type, rarity: { name, color } | null, price: { amount, label, currency, currencyIcon, regular }, images: { card, render }, badge, availability: { from, until, untilLabel }, bundle, contents: [...], soldOut, sourceUrl }.
- Many fields can be null; handle that. price.amount is null when the store shows no number, and price.label then holds a word such as "Included". price.currency is the game currency's name, or an ISO code like "USD" for real money. Sections with upcoming: true can't be bought yet. An empty sections list with stale: false is a genuinely empty shop.
- Write types for these shapes in this project's language.

Being a good client
- Cache answers: shops change every few minutes at most, and an answer is good for about two minutes. Send back the ETag as If-None-Match and treat 304 as "unchanged".
- The limit is 600 requests a minute per key. On 429, wait for the Retry-After header's seconds before trying again.
- Errors are { error: { code, message } }. Handle 401 (key_required or invalid_key: the key is missing, wrong or revoked), 404 (unknown_game, not_recorded, unknown_item, no_items), 429 and 503 (try again later).
- Set a User-Agent header that names this project.

Required by the terms
- Wherever the data is shown, show a visible link: "Data from itemshop.gg", linking to meta.attribution.url from the answer. Add it to the UI you build.

Start by asking me what I want built with it (for example a Discord bot command, a site widget or a daily post), unless I've already said, then implement it following the existing patterns in this codebase.

Questions