Microsoft Store API — v2 Reference

The XBXprices Microsoft Store API v2 is a REST API returning clean JSON for Xbox Series X|S & Xbox One prices, price history, live sales/discounts and achievement data across 70+ regions. The base URL is:

/api/v2

How regions work — read this first

This is the one thing almost everyone trips over on day one, so here it is up front. Xbox has no single global store — every country runs its own Microsoft Store, with its own prices, currency, release dates and even its own list of which games exist. The API mirrors that exactly.

Quickstart — from key to first JSON in 5 minutes

Just received your API key by email? Follow these steps in order — especially step 2 (regions), the thing most new integrations trip over. No key yet? Open the keyless /demo in your browser to see the data shape, and grab a key via the plans page.

Step 1 — check that your key works

GET /account is free (it never consumes a request) and shows everything about your key: plan, monthly quota, expiry and — crucially — which store regions it can query.

curl -H "X-API-Key: $PP_KEY" "/api/v2/account"

{
  "success": true,
  "data": {
    "plan": "indie",
    "monthly_limit": 20000,
    "remaining_this_month": 20000,
    "regions": {
      "allowed_regions": ["DE", "FR", "GB", "JP", "US"],   // <-- what you may query
      "region_limit": 5,
      "source": "plan_default",
      "can_change_now": true
    }
  }
}

Getting 401 instead? Make sure the header is exactly X-API-Key and the key was copied without spaces or line breaks.

Step 2 — set the regions you actually need (the #1 gotcha)

Every data request is scoped to one store region via the region= parameter — and if you omit it, it defaults to US. New keys start with your plan’s default region set (for Indie: US, GB, DE, FR, JP). Requesting a region that is not enabled for your key returns 403 REGION_NOT_IN_PLAN — that is configuration, not a broken key. Pick your own set (up to your plan’s limit) with one call:

# Example: an Indie key (5 regions) that needs Ukraine + Turkey
curl -X PUT -H "X-API-Key: $PP_KEY" -H "Content-Type: application/json" \
     -d '{"regions":["US","GB","UA","TR","DE"]}' \
     "/api/v2/account/regions"

The change is immediate. Valid codes come from GET /regions; regions can be changed once every 24 hours (re-submitting the same list is a free no-op), so pick the set you need before you start. The same control exists on your developer dashboard.

Step 3 — your first data request

# Search a game by name in the Turkish store
curl -H "X-API-Key: $PP_KEY" \
  "/api/v2/games/search?q=Resident+Evil+4&region=tr"

# Everything on sale in the Ukrainian store, biggest discounts first
curl -H "X-API-Key: $PP_KEY" \
  "/api/v2/deals?region=ua&sort=discount&order=desc&limit=20"

Remember: always pass region= explicitly — it makes your intent unambiguous and your caching keys clean.

Step 4 — the same call in your language

// JavaScript (Node 18+ / browser)
const res  = await fetch("/api/v2/deals?region=ua&limit=20", {
  headers: { "X-API-Key": "$PP_KEY" }
});
const json = await res.json();
if (!json.success) throw new Error(json.error.code + ": " + json.error.message);
console.log(json.data.length, "deals; first:", json.data[0].ProductName);

# Python 3 (requests)
import requests

r = requests.get(
    "/api/v2/deals",
    params={"region": "ua", "limit": 20},
    headers={"X-API-Key": "$PP_KEY"},
    timeout=15,
)
j = r.json()
if not j["success"]:
    raise RuntimeError(f"{j['error']['code']}: {j['error']['message']}")
for game in j["data"]:
    print(game["ProductName"], game["formattedSalePrice"])

<?php // PHP 8 (cURL)
$ch = curl_init("/api/v2/deals?region=ua&limit=20");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['X-API-Key: $PP_KEY'],
    CURLOPT_TIMEOUT        => 15,
]);
$j = json_decode(curl_exec($ch), true);
if (!($j['success'] ?? false)) {
    throw new RuntimeException($j['error']['code'] . ': ' . $j['error']['message']);
}
foreach ($j['data'] as $game) {
    echo $game['ProductName'], ' — ', $game['formattedSalePrice'], "\n";
}

Step 5 — watch your quota, handle errors

Every response carries X-RateLimit-Remaining (and meta.rate_limit); GET /status and GET /account/usage are free ways to check usage. Always branch on error.code — the most common first-day issues:

Full error reference is below. Stuck? Email [email protected] with the request URL and the JSON error you got — we answer fast.

Authentication

Every request (except /demo) needs an API key, sent in the X-API-Key request header. A ?key= query parameter is also accepted for backward compatibility with v1.

curl -H "X-API-Key: $PP_KEY" "/api/v2/games?region=us&limit=5"

Keys are issued by email — tell us about your project at [email protected]. Keep your key secret; treat it like a password.

Fully self-service by key — no website account needed. Everything about your key is manageable through the API itself: GET /account (plan, quota, expiry, regions), GET /account/usage (daily request history + per-endpoint breakdown) and PUT /account/regions (choose which store regions your key serves). All three are free — they never consume a request. Prefer a UI? The same controls live on your developer dashboard.

# Choose your regions — by key alone, no account needed
curl -X PUT -H "X-API-Key: $PP_KEY" -H "Content-Type: application/json" \
     -d '{"regions":["US","GB","DE"]}' "/api/v2/account/regions"

Plans & limits

Quotas are counted per calendar month and reset on the 1st (UTC). Region access and price history depend on your plan.

Price history (/games/{ppid}/price-history) is a paid feature: on the Free plan it returns 403 PLAN_UPGRADE_REQUIRED. The history window is plan-tied — Indie and Pro see the last 3 months, Business the last 12 months; need a deeper or full-archive export? Talk to us. If you request a region outside your plan you get 403 REGION_NOT_IN_PLAN — configure your allowed regions or upgrade.

Sale archive follows the same window: /sales/{id} serves any active or recently ended sale, but a sale that ended beyond your plan’s history window returns 403 SALE_ARCHIVE_WINDOW.

Terms of use. Use the API in your apps, dashboards, analytics and alerts. Don’t build a directly competing price-tracking service, resell or redistribute the raw data, bulk-archive beyond your plan’s limits, or scrape the website to get around them. Where your plan requires attribution, show “Powered by XBXprices” with a link. Violating keys may be throttled or revoked.

{
  "success": true,
  "data": { ... } | [ ... ] | null,
  "meta": {
    "region": "US",
    "pagination": { "page": 1, "limit": 20, "total": 134 },
    "rate_limit": { "limit": 50000, "used": 12, "remaining": 49988, "reset_at": "2026-07-01T00:00:00Z" },
    "response_ms": 14
  },
  "error": null
}

Endpoints

Quick reference — tap a path to jump to its full details.

Tap any path above for its full parameters and response — or switch to the full reference to read every endpoint in detail.

Examples

# Trending deals in the UK, biggest discounts first
curl -H "X-API-Key: $PP_KEY" \
  "/api/v2/deals?region=gb&sort=discount&order=desc&limit=20"

# One game by Xbox bigId, with related editions
curl -H "X-API-Key: $PP_KEY" \
  "/api/v2/games/by-psnid/PPSA07412?region=us&include_related=1"

# Price history (paid plans; 3 months back, Business 12)
curl -H "X-API-Key: $PP_KEY" \
  "/api/v2/games/7704/price-history?region=us"

# No key needed — try this one in your browser:
curl "/api/v2/demo"

The keyless /demo endpoint returns a real sample response so you can see the shape of the data before you get a key.

Questions, a higher limit, or a custom plan? Email [email protected].