Kinguin Purchase API (ESA) — Integration Guide

This is the definitive guide to the Kinguin Purchase API, also known as ESA (API for External Stores). It is for developers who want to buy products from Kinguin programmatically and covers everything needed to build a reliable integration — from authentication and catalog sync, through orders and webhooks, to keys and returns.

While the API Reference describes each endpoint, this guide explains how they work together: what the stock fields mean, when a product goes out of stock, how to keep your catalog up to date efficiently, and which rules apply to pre-orders, wholesale and returns.

ResourceLink
API Referencehttps://www.kinguin.net/dev-portal/esa-documentation
OpenAPI specificationhttps://www.kinguin.net/services/esa/api/info

1. Basics

Environments

EnvironmentAPI base URLWebsite
Sandboxhttps://gateway.sandbox.kinguin.net/esahttps://sandbox.kinguin.net
Productionhttps://gateway.kinguin.net/esahttps://www.kinguin.net

Build and test your integration against the sandbox first.

Getting sandbox access. Registration in the sandbox works exactly the same way as in production: create an account on the sandbox website, create your store in the dashboard and generate the store's API key there. The sandbox balance is topped up by your Kinguin business manager — contact them once your sandbox store is ready.

Production balance. All orders are paid from your prepaid Kinguin balance. To top it up, contact your business manager.

Authentication

Every request must contain your store's API key in the X-Api-Key header.

export ESA_URL="https://gateway.sandbox.kinguin.net/esa"
export ESA_KEY="your-api-key"

curl -H "X-Api-Key: $ESA_KEY" "$ESA_URL/api/v1/balance"
StatusWhen
401 UnauthorizedThe API key is missing or invalid
403 ForbiddenThe key is valid, but the operation is not allowed — e.g. the request comes from an IP address that is not on your whitelist (Security)

API versions — v1 vs v2

Both versions are live and share the same data. The main difference is the product identifier used when creating orders:

v1v2
Product identifier in orderskinguinId (integer)productId (string)
Product listGET /api/v1/products — deprecatedGET /api/v2/products
Single productGET /api/v1/products/{kinguinId}GET /api/v2/products/{productId}
Create orderPOST /api/v1/orderPOST /api/v2/order
Order details / listGET /api/v1/order/{orderId}, GET /api/v1/ordersame endpoints
Keys / returns—GET /api/v2/order/{orderId}/keys, POST /api/v2/order/{orderId}/keys/return

Every product carries both kinguinId and productId, so store both in your database. For new integrations use v2 endpoints wherever they exist.


2. Security

API key

  • Send it only in the X-Api-Key header, over HTTPS, from your backend. Never expose it in a browser, mobile app or public repository.
  • Keep it in a secrets manager or environment variable.
  • Use separate keys for sandbox and production.
  • If a key leaks, contact your business manager immediately.

Webhook secret

Configure a secret in the dashboard. Kinguin sends it in X-Event-Secret on every webhook. Reject any request where it does not match, using a constant-time comparison. Use a long random value and serve your endpoint only over HTTPS.

Store IP whitelist

You can restrict ordering, dispatching and key retrieval to a list of your server IP addresses. The whitelist is configured per store.

Contact your business manager and send the list of your store's outgoing IP addresses. From then on, these operations from other IPs are rejected with 403 Forbidden.

  • Use static egress IPs (NAT gateway, fixed proxy) — dynamic cloud IPs will break your integration.
  • Notify your business manager before changing infrastructure or IPs.

Balance as a safety limit

Orders are paid from your prepaid balance. Keeping it at a level matching your expected turnover limits the damage of a compromised key. Monitor it with GET /api/v1/balance and alert on unexpected drops. Insufficient funds produce kind: "InsufficientBalance".


3. Rate limits

SettingValue
Limit2000 RPM
Period60 seconds
HTTP methods countedPOST, PUT, DELETE, PATCH
Hostgateway.kinguin.net
Response when exceeded429 Too Many Requests

Requests over the limit may be rejected or delayed. Design your integration to stay below it:

  • On 429, back off exponentially with jitter before retrying.
  • Never retry POST /order blindly — look the order up by orderExternalId first.
  • Queue outgoing orders during traffic peaks instead of firing them all at once.
  • Keep read traffic efficient as well: use webhooks and updatedSince instead of polling the full catalog, use projection=stock, batch up to 25 IDs per request, use limit=100 when paginating and cache dictionaries (/genres, /platforms, /regions).

4. Error handling

All error responses use the same JSON format:

{
  "kind": "ProductUnavailable",
  "reason": "InvalidPrice",
  "status": 422,
  "type": "Unprocessable Entity",
  "method": "POST",
  "detail": "Human-readable description",
  "path": "/api/v2/order",
  "timestamp": "2026-10-16T11:24:08.015+00:00"
}

Always branch on kind and reason. detail is for humans and logs only — its wording can change at any time.

kind

kindHTTP statusTypical causeSuggested action
ConstraintViolation400, 422Invalid request (missing field, qty out of range, too many items)Fix the request
Authorization401, 403Invalid key, forbidden operation, IP not whitelistedCheck the key / whitelist
InsufficientBalance422Not enough balanceNo order is created. Top up your balance, then retry
ProductUnavailable422See reasonSee table below
Preorder422Pre-order rules violatedSee Pre-orders
ProductNotFound404Unknown product, or the product is currently out of stockHide it from your storefront — see Out of stock
OrderFailed500Order could not be placedRetry later; contact support if persistent
OrderExternalNotUnique409The orderExternalId has already been used in your accountUse a new orderExternalId, or — when retrying after a timeout — fetch the existing order by orderExternalId
OrderNotFound404Unknown orderCheck orderId
OrderNotSupported422Operation not supported for this order (e.g. returning wholesale)—
NoKeysToReturn422Nothing eligible to return—
Http, HttpClient, Error4xx, 5xxUnexpected errorsRetry with backoff; contact support if persistent

HTTP 429 Too Many Requests means the rate limit was exceeded.

reason (for ProductUnavailable)

reasonMeaningSuggested action
NoStockNot enough quantity (or text quantity with keyType: "text")Mark out of stock / lower qty
NoOffersNo offers, or the given offerId no longer existsMark out of stock / refresh offers
InvalidPriceYour price is below the current priceRefresh the price, re-check your margin
OfferRequiredofferId needed (wholesale)Add offerId
WholesaleNotAvailableWholesale not possible for this offer/quantityPick another offer / lower qty
NoTierNo wholesale tier for the quantityAdjust qty

5. Webhooks

Webhooks are HTTP POST requests Kinguin sends to your endpoint when something changes. They are the primary way to keep your catalog and orders in sync.

Event types

Event (X-Event-Name)Triggered when
product.updateProduct data changed, stock or price changed, the product went out of stock, or a new offer became available
product.update.bulkThe same changes as product.update, delivered for many products in a single request
order.statusAn order's status changed
order.completeAn order has been completed

Headers

HeaderValue
X-Event-Name (always)Event name
X-Event-SecretThe secret you configured — verify it on every request
Content-Typeapplication/json

Do not use any header that is not documented in the table above in your integration.

product.update payload

{
  "kinguinId": 1949,
  "productId": "5c9b5f6b2539a4e8f172916a",
  "qty": 845,
  "textQty": 845,
  "totalQty": 1290,
  "cheapestOfferId": ["611222acff9ca40001f0b020"],
  "updatedAt": "2020-10-16T11:24:08.015+00:00"
}
FieldTypeDescription
kinguinIdintProduct ID (v1)
productIdstringProduct ID (v2)
qtyintQuantity of the cheapest offer(s) — same meaning as product qty
textQtyintText-serial quantity of the cheapest offer(s)
totalQtyintQuantity across all offers — same meaning as product totalQty
cheapestOfferIdstring[]Cheapest offer IDs
updatedAtstringChange time, Y-m-d\TH:i:s.vP

The payload does not contain the price or the offer list. Fetch the product with projection=stock when you need them (see section 7).

product.update.bulk payload

The payload is an array of product.update payloads — each element has exactly the same fields and meaning as described above.

[
  {
    "kinguinId": 1949,
    "productId": "5c9b5f6b2539a4e8f172916a",
    "qty": 845,
    "textQty": 845,
    "totalQty": 1290,
    "cheapestOfferId": ["611222acff9ca40001f0b020"],
    "updatedAt": "2020-10-16T11:24:08.015+00:00"
  },
  {
    "kinguinId": 2057,
    "productId": "5c9b5f6b2539a4e8f172916b",
    "qty": 0,
    "textQty": 0,
    "totalQty": 0,
    "cheapestOfferId": [],
    "updatedAt": "2020-10-16T11:24:08.120+00:00"
  }
]

A single bulk payload can contain several elements for the same product (the same productId / kinguinId). Before processing, sort the elements by updatedAt and keep only the newest element per product (parse updatedAt as a date-time rather than comparing it as text).

Then handle each remaining element exactly like a single product.update: compare its updatedAt with the stored value and skip elements that are older than the data you already have. The bulk variant reduces the number of HTTP requests your endpoint has to accept, which matters when many products change at once. Its product IDs also map directly to the batched projection=stock refresh described in Catalog sync.

order.status payload

{
  "orderId": "PHS84FJAG5U",
  "orderExternalId": "AL2FEEHOO2OHF",
  "status": "completed",
  "updatedAt": "2020-10-16T11:24:08.025+00:00"
}

order.complete payload

{
  "orderId": "PHS84FJAG5U",
  "orderExternalId": "AL2FEEHOO2OHF",
  "updatedAt": "2020-10-16T11:24:08.025+00:00"
}
FieldTypeDescription
orderIdstringKinguin order ID
orderExternalIdstring | nullYour order reference; null if the order was created without it
updatedAtstringCompletion time, Y-m-d\TH:i:s.vP

When you receive order.complete or order.status with status: "completed", all of the order's keys are ready to download — see Keys.

Delivery and retries

  • Respond with any 2xx status and an empty body. 204 No Content is recommended.
  • If delivery fails, Kinguin retries it up to 5 times. The interval between retries depends on the current system load. After the last failed retry the webhook is dropped.
  • If no webhook can be delivered to your endpoint for 6 hours, the webhook subscription is disabled automatically. To enable it again, save the webhook configuration in the dashboard once more.
  • Respond fast, process later. Put the payload on a queue and return 204 immediately.
  • Delivery order is not guaranteed. Store updatedAt per product/order and ignore webhooks older than the data you already have.
  • Duplicates are possible. Make processing idempotent.
  • Run a periodic reconciliation with updatedSince to catch anything that was dropped (see Catalog sync).

6. Products and offers

Product vs offer

  • A product is a catalog item (e.g. Counter-Strike: Source Steam CD Key, region Global, platform Steam).
  • An offer is a specific merchant's listing of that product with its own price and stock. One product can have many offers.

When you order without an offerId, Kinguin picks the cheapest offer for you. When you pass offerId, you buy from that specific offer.

Identifiers

FieldWhereMeaning
kinguinIdproductInteger product ID, used by v1 orders
productIdproductString product ID, used by v2 orders
offers[].offerIdproductOffer ID; required for wholesale orders, optional otherwise
cheapestOfferId[]product, webhookIDs of all offers sharing the lowest price

Stock fields explained

Stock fields appear on two levels: on the product and on each of its offers (offers[]). Fields with the same name, such as qty, mean different things on each level.

Product

FieldMeaning
qtyQuantity of the cheapest offer(s) (those listed in cheapestOfferId)
textQtyText-serial part of qty
totalQtyQuantity across all offers
pricePrice of the cheapest offer, EUR
cheapestOfferId[]IDs of all offers sharing the lowest price
offersCountNumber of offers
merchantName[]Merchant names behind the cheapest offers

The product.update and product.update.bulk webhooks carry the product-level qty, textQty, totalQty and cheapestOfferId with exactly the same meaning — see Webhooks.

Offer (offers[])

FieldMeaning
qtyTotal quantity of keys available for this offer
textQtyText-serial part of this offer's qty
availableQtyPhysical quantity of keys uploaded to Kinguin, independent of the quantity declared in the offer
availableTextQtyText-serial part of availableQty
pricePrice of this offer, EUR
wholesaleWholesale configuration — see Wholesale

qty vs availableQty. qty is the quantity the offer declares and sells — use it (or textQty) to decide whether you can buy. availableQty / availableTextQty show how many keys are physically uploaded at the moment; the number is not tied to the declared offer quantity, so it can be higher or lower than qty.

Listing products

curl -G -H "X-Api-Key: $ESA_KEY" "$ESA_URL/api/v2/products" \
  --data-urlencode "page=1" \
  --data-urlencode "limit=100" \
  --data-urlencode "platform=Steam" \
  --data-urlencode "tags=base,dlc"

Response shape (v2):

{
  "_embedded": {
    "products": [
      {
        "kinguinId": 1949,
        "productId": "5c9b5f6b2539a4e8f172916a",
        "cheapestOfferId": ["5f7efe3b369b4a0001c5b46f"],
        "name": "Counter-Strike: Source Steam CD Key",
        "originalName": "Counter-Strike: Source",
        "description": "Counter-Strike: Source blends Counter-Strike's award-winning teamplay action with the technology of the Source engine...",
        "developers": ["Valve Corporation"],
        "publishers": ["Valve Corporation"],
        "genres": ["Action", "FPS"],
        "platform": "Steam",
        "releaseDate": "2004-11-01",
        "qty": 149,
        "textQty": 149,
        "totalQty": 412,
        "price": 5.79,
        "offersCount": 3,
        "offers": [
          {
            "offerId": "5f7efe3b369b4a0001c5b46f",
            "name": "Counter-Strike: Source Steam CD Key",
            "price": 5.79,
            "qty": 149,
            "textQty": 149,
            "availableQty": 149,
            "availableTextQty": 149,
            "isPreorder": false,
            "releaseDate": "2004-11-01",
            "wholesale": {
              "enabled": true,
              "tiers": [
                {
                  "level": 1,
                  "price": 5.5
                },
                {
                  "level": 2,
                  "price": 5.4
                },
                {
                  "level": 3,
                  "price": 5.3
                },
                {
                  "level": 4,
                  "price": 5.2
                }
              ]
            }
          },
          {
            "offerId": "5f7efe3b369b4a0001c5b470",
            "name": "Counter-Strike: Source Steam CD Key",
            "price": 6.10,
            "qty": 200,
            "textQty": 0,
            "availableQty": 50,
            "availableTextQty": 0,
            "isPreorder": false,
            "releaseDate": "2004-11-01",
            "wholesale": { "enabled": false, "tiers": [] }
          },
          {
            "offerId": "5f7efe3b369b4a0001c5b471",
            "name": "Counter-Strike: Source Steam CD Key",
            "price": 6.49,
            "qty": 63,
            "textQty": 63,
            "availableQty": 63,
            "availableTextQty": 63,
            "isPreorder": false,
            "releaseDate": "2004-11-01",
            "wholesale": { "enabled": false, "tiers": [] }
          }
        ],
        "isPreorder": false,
        "metacriticScore": 88,
        "regionalLimitations": "REGION FREE",
        "regionId": 3,
        "countryLimitation": [],
        "activationDetails": "Go to: http://store.steampowered.com/ and download STEAM client. Click \"Install Steam\"...",
        "videos": [
          { "video_id": "a1b2c3d4e5f", "video_url": "https://www.youtube.com/watch?v=a1b2c3d4e5f" }
        ],
        "languages": ["English", "German", "French"],
        "systemRequirements": [
          { "system": "Windows", "requirement": "OS: Windows XP; Processor: 1.7 GHz; Memory: 512 MB RAM" }
        ],
        "tags": ["base"],
        "merchantName": ["KinguinHK"],
        "ageRating": "PEGI 16",
        "steam": 240,
        "images": {
          "cover": {
            "url": "https://static.kinguin.net/media/images/products/cover.jpg",
            "thumbnail": "https://static.kinguin.net/media/images/products/cover_thumb.jpg"
          },
          "screenshots": [
            {
              "url": "https://static.kinguin.net/media/images/products/screenshot1.jpg",
              "thumbnail": "https://static.kinguin.net/media/images/products/screenshot1_thumb.jpg"
            }
          ]
        },
        "updatedAt": "2026-10-16T11:24:08.015+00:00"
      }
    ]
  },
  "page": {
    "totalElements": 81234,
    "totalPages": 813,
    "number": 1,
    "size": 100
  }
}
FieldMeaning
_embedded.products[]Products on the current page
page.totalElementsTotal number of products matching the filters
page.totalPagesTotal number of pages
page.numberCurrent page number
page.sizePage size (limit)

The stock projection

projection=stock returns a slim object with only: kinguinId, productId, cheapestOfferId, qty, textQty, totalQty, price, offers (with offerId, price, qty, textQty, availableQty, availableTextQty), offersCount and updatedAt. It is much smaller and faster than the full product and is the recommended way to refresh stock and prices. It works on GET /api/v2/products, GET /api/v2/products/{productId} and GET /api/v1/products/{kinguinId}.

curl -G -H "X-Api-Key: $ESA_KEY" "$ESA_URL/api/v2/products" \
  --data-urlencode "productId=5c9b5f6b2539a4e8f172916a,5c9b5f6b2539a4e8f172916b" \
  --data-urlencode "projection=stock"

7. Catalog sync

Keep a local copy of the Kinguin catalog that stays accurate while using as few API requests as possible. The recommended approach combines four elements: a one-time initial import, webhooks for real-time changes, the stock projection for lightweight refreshes, and periodic reconciliation to catch anything the webhooks missed.

000_202610231140_esa-api-guide-7-catalog-sync-flow-chart.png

Step 1 — Initial import

Paginate through the full catalog once, with the default projection, to get names, images, regions and so on.

curl -G -H "X-Api-Key: $ESA_KEY" "$ESA_URL/api/v2/products" \
  --data-urlencode "page=1" \
  --data-urlencode "limit=100" \
  --data-urlencode "sortBy=kinguinId" \
  --data-urlencode "sortType=asc"

Continue until page.number == page.totalPages. Record the time the import started — this is your first updatedSince checkpoint.

If you sell only a subset (e.g. only Steam, only text keys), apply filters (platform, tags, regionId, withText=Yes) to import less.

Step 2 — Real-time updates via webhooks

product.update and product.update.bulk give you the new qty, textQty, totalQty and cheapestOfferId — enough to switch a product between in stock and out of stock immediately. To get the new price and offers, refresh the product with projection=stock.

Prefer product.update.bulk when your catalog is large: one request carries many product changes, so your endpoint handles far fewer calls during peaks.

Do not call the API once per changed product. Batch product IDs from incoming webhooks (for example collect them for 5–30 seconds, or split a bulk payload into groups) and fetch them together — up to 25 IDs per request:

curl -G -H "X-Api-Key: $ESA_KEY" "$ESA_URL/api/v2/products" \
  --data-urlencode "productId=5c9b5f6b2539a4e8f172916a,5c9b5f6b2539a4e8f172916b,5c9b5f6b2539a4e8f172916c" \
  --data-urlencode "projection=stock" \
  --data-urlencode "limit=25"

Step 3 — Periodic reconciliation with updatedSince

Webhooks can be dropped (endpoint down, retries exhausted). Every few minutes, fetch everything that changed since your last checkpoint, using the stock projection:

curl -G -H "X-Api-Key: $ESA_KEY" "$ESA_URL/api/v2/products" \
  --data-urlencode "updatedSince=2026-10-16T10:00:00+00:00" \
  --data-urlencode "projection=stock" \
  --data-urlencode "sortBy=updatedAt" \
  --data-urlencode "sortType=asc" \
  --data-urlencode "limit=100" \
  --data-urlencode "page=1"
  • updatedSince cannot be older than 7 days. If your integration was down longer, run a full import again.
  • updatedTo cannot be in the future.
  • Use a small overlap (checkpoint minus 1–2 minutes) to avoid gaps; the updatedAt comparison removes duplicates.
  • Advance the checkpoint only after all pages were processed successfully.
  • Out-of-stock products are not returned here, so a product that sold out while a webhook was lost will not show up in reconciliation. To catch it, periodically check the products you show as in stock by ID (up to 25 per request, projection=stock): any ID missing from the response is out of stock — hide it.

Step 4 — Refresh descriptive data occasionally

Names, descriptions, images and system requirements change rarely. Refresh them with the default projection once a day for products whose updatedAt changed, and for newly seen products.

Step 5 — Final check at checkout

Even a perfectly synced catalog can be a few seconds behind. Right before buying, fetch the single product with projection=stock — a 404 / ProductNotFound response means it is out of stock — and handle ProductUnavailable on order creation (see section 8).


8. Orders

POST /api/v2/order        (uses productId)
POST /api/v1/order        (uses kinguinId)

Request fields

FieldRequiredDescription
products[]yes1–10 items
products[].productId (v2) / kinguinId (v1)yesProduct identifier
products[].qtyyes1–9 for regular orders; up to 1000 for wholesale
products[].priceyesMaximum unit price in EUR you accept. Cannot be lower than the current cheapest price.
products[].offerIdnoBuy from a specific offer. If omitted, the cheapest offer is used. Required for wholesale.
products[].keyTypenotext — deliver only text serials. See Text keys.
orderExternalIdnoYour own order reference, unique within your account. Strongly recommended.

Currency

All prices in the API are in EUR — product and offer prices, wholesale tier prices, the price you send when ordering, order totals and your balance.

How price works

price is a ceiling. You pay the actual offer price, reported back as products[].price and paymentPrice. If the current price is higher than your ceiling, the order is rejected (ProductUnavailable / InvalidPrice) and nothing is charged. Set the ceiling to the highest price at which the sale is still profitable for you.

Order response fields

FieldMeaning
orderIdKinguin order ID — use it for keys, returns and lookups
orderExternalIdYour reference
statusOrder status
totalPriceTotal order price, EUR
requestTotalPriceTotal calculated from the price values you sent, EUR
paymentPriceBalance actually charged, EUR
products[].keys[]Per-key id and status

Order statuses

StatusMeaning
processingOrder created, keys are being delivered
completedAll keys delivered — you can download them
canceledOrder could not be fulfilled
refundedKeys were returned and the balance refunded

Key statuses

Each key in products[].keys[] has one of: PENDING, PROCESSING, DELIVERED, RETURNED, REFUNDED, CANCELED.

Use orderExternalId to stay safe on timeouts

orderExternalId is unique within your account, which makes it a reliable reference for your own order. If your POST /order request times out, do not blindly create a new order — look the order up by your reference first:

curl -G -H "X-Api-Key: $ESA_KEY" "$ESA_URL/api/v1/order" \
  --data-urlencode "orderExternalId=MYSHOP-100045"

If no order is found, retry creation with the same orderExternalId. If the retry returns OrderExternalNotUnique, the original order was created after all — fetch it by orderExternalId instead of creating a new one.

Listing orders

GET /api/v1/order supports page, limit, createdAtFrom, createdAtTo, kinguinId, productId, orderId, orderExternalId, status and isPreorder. It returns only orders of the store that owns the API key.

Verifying that an order will go through

There is no dry-run endpoint — the order request itself is the authoritative check. Recommended pattern:

  1. Just before checkout, fetch the product with projection=stock and confirm qty > 0 (or textQty > 0 with keyType: "text") and that price fits your margin.
  2. Create the order with a sensible price ceiling.
  3. If it fails with ProductUnavailable, use reason to decide what to do (show "out of stock", re-price, try another offer).

For the best customer experience, authorize your customer's payment, buy on Kinguin, and capture the payment only after the Kinguin order is created — or refund your customer automatically when the purchase fails.


9. Keys

GET /api/v2/order/{orderId}/keys?page=1&limit=100
curl -G -H "X-Api-Key: $ESA_KEY" "$ESA_URL/api/v2/order/PHS84FJAG5U/keys" \
  --data-urlencode "page=1" \
  --data-urlencode "limit=100"

The response is an array of serials:

[
  {
    "id": "6a1f3c9e8b7d4e2f9a0b1c2d",
    "name": "Counter-Strike: Source Steam CD Key",
    "type": "text/plain",
    "serial": "ABCDE-FGHIJ-KLMNO",
    "kinguinId": 1949,
    "productId": "5c9b5f6b2539a4e8f172916a",
    "offerId": "5f7efe3b369b4a0001c5b46f"
  },
  {
    "id": "6a1f3c9e8b7d4e2f9a0b1c2e",
    "name": "Counter-Strike: Source Steam CD Key",
    "type": "image/png",
    "serial": "iVBORw0KGgoAAAANSUhEUgAA...",
    "kinguinId": 1949,
    "productId": "5c9b5f6b2539a4e8f172916a",
    "offerId": "5f7efe3b369b4a0001c5b470"
  }
]

Each serial contains:

FieldMeaning
idKey identifier
nameProduct name
typetext/plain, image/jpeg, image/png or image/gif
serialThe key. Base64-encoded for image types.
kinguinId, productId, offerIdOrigin of the key

Handling image keys: decode serial from base64 and save or display it using the MIME type from type (jpeg, png or gif).

Rules

  1. A key becomes claimed the first time it is downloaded. From that moment it can no longer be returned.
  2. Download keys only when you are about to deliver them to your customer, after the order is completed.
  3. For orders with more than 100 keys (wholesale), iterate pages until a page returns fewer items than limit.
  4. Store keys encrypted at rest — they are equivalent to money.

10. Out of stock

A product is out of stock when none of its offers has remaining quantity. At that moment Kinguin sends a product.update webhook (or an element of product.update.bulk) with "totalQty": 0. Hide the product as soon as you receive it.

Use totalQty (not qty) to decide whether a product is out of stock: qty only describes the cheapest offer(s), while totalQty covers all offers.

While a product is out of stock, it disappears from every product endpoint: it is not returned by GET /api/v2/products (including results filtered with updatedSince or by IDs), and requesting it directly (GET /api/v2/products/{productId} or GET /api/v1/products/{kinguinId}) returns HTTP 404 with kind: "ProductNotFound".

Treat this response as "currently out of stock", not as "deleted": keep the product in your database, hide it from your storefront and show it again when a product.update webhook reports totalQty > 0.

Situations that look similar but are different:

  • The cheapest offer sells out, other offers remain. The product stays available, but its price, qty, cheapestOfferId and merchantName change. You get a product.update webhook for this change too — refresh the price before selling.
  • A specific offer sells out. The offer disappears from offers. Ordering with that offerId fails with ProductUnavailable / NoOffers.
  • The price rises above your limit. Ordering with a price below the current price fails with ProductUnavailable / InvalidPrice.
  • Only text stock runs out. A product can be in stock with textQty = 0. Ordering with keyType: "text" and no offerId then fails with ProductUnavailable / NoStock; to buy text keys from a more expensive offer, pass its offerId (see Text keys). Track textQty separately if you buy text keys only.

Stock changes continuously because many buyers order at the same time. Between a webhook being sent and you processing it, keys may already be sold. Treat order creation as the final availability check — see Verifying that an order will go through.


11. Text keys

Keys are delivered either as plain text (text/plain) or as images (image/jpeg, image/png, image/gif, base64-encoded in serial). If your store handles text only, request text serials explicitly.

Rules

  1. text is the only value of keyType. Image keys cannot be requested explicitly; without keyType you may receive a mix of text and image keys.
  2. Without offerId, keyType: "text" uses only the cheapest offer(s). If they have no text keys (product textQty = 0), the order fails with ProductUnavailable / NoStock — even if a more expensive offer has text keys. In that case, pick an offer with textQty > 0 from offers[] and pass its offerId.
  3. When keyType: "text" is combined with offerId, the text serials come from that offer's text stock.
  4. keyType is not allowed for pre-orders.

To find products with text stock, list products with withText=Yes: GET /api/v2/products?withText=Yes, then check textQty > 0 on the product, or textQty on the offer. When ordering, add "keyType": "text" to each order item. availableTextQty > 0 on an offer means its text keys are physically uploaded to Kinguin. textQty in product.update webhooks lets you track text availability separately.


12. Pre-orders

A pre-order is a product with isPreorder: true sold before its releaseDate. Keys are delivered after release.

Rules

  1. keyType is not allowed in pre-order items.
  2. Only one pre-order item per request.
  3. Pre-orders cannot be mixed with regular products in one order.
  4. Pre-orders cannot be returned.

To find pre-orders available for purchase, list products with activePreorder=Yes: GET /api/v2/products?activePreorder=Yes. A pre-order is bought like any other product, with POST /api/v2/order, as long as the rules above are followed.

The order stays in processing until release. When the keys are delivered, you receive order.status with completed and can download them as usual. Breaking the rules above returns an error with kind: "Preorder".

To list your pre-orders, use GET /api/v1/order?isPreorder=Yes.


13. Wholesale

Wholesale lets you buy larger quantities (10–1000) of a single offer at tiered prices.

Rules

  1. offerId is required.
  2. Max quantity per offer: 1000. Max total order quantity: 1000.
  3. Only offers with wholesale.enabled = true, and only for quantity ≥ 10.
  4. Wholesale orders cannot be returned.
  5. For orders with more than 100 keys, download keys with pagination.

Tiers

LevelQuantity
110+
250+
3100+
4500+

Step by step

  1. In the product's offers[], pick an offer with wholesale.enabled: true and enough qty, and take the tier price for your quantity — for 50 keys, level 2 → 5.4:
"wholesale": {
  "enabled": true,
  "tiers": [
    {
      "level": 1,
      "price": 5.5
    },
    {
      "level": 2,
      "price": 5.4
    },
    {
      "level": 3,
      "price": 5.3
    },
    {
      "level": 4,
      "price": 5.2
    }
  ]
}
  1. Create the order with that offerId and the tier price:
curl -X POST "$ESA_URL/api/v2/order" \
  -H "X-Api-Key: $ESA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "products": [
      {
        "productId": "5c9b5f6b2539a4e8f172916a",
        "offerId": "5f7efe3b369b4a0001c5b46f",
        "qty": 50,
        "price": 5.4
      }
    ]
  }'
  1. Download the keys page by page (see Keys).

Wholesale-specific errors

When a wholesale order cannot be placed, you get kind: "ProductUnavailable" with a structured reason:

reasonMeaningWhat to do
OfferRequiredofferId missing for a quantity above the regular limitAdd offerId
WholesaleNotAvailableWholesale is not enabled for this offer, or the quantity cannot be servedChoose another offer or lower the quantity
NoTierNo tier matches the quantityAdjust the quantity
InvalidPriceprice lower than the tier priceUse the correct tier price
NoStockNot enough stockLower the quantity

Always branch on kind and reason, never on the human-readable detail text — its wording may change.


14. Returns and refunds

POST /api/v2/order/{orderId}/keys/return

The endpoint returns all keys of the order that meet the requirements, and the corresponding amount is refunded to your Kinguin balance while the request is processed.

curl -X POST -H "X-Api-Key: $ESA_KEY" \
  "$ESA_URL/api/v2/order/PHS84FJAG5U/keys/return"
[
  { "id": "6a1f...e01", "status": "RETURNED" },
  { "id": "6a1f...e02", "status": "RETURNED" }
]

Rules

A key can be returned only when all of the following are true:

  1. The key has not been claimed — it has never been downloaded via GET /api/v2/order/{orderId}/keys.
  2. The order contains no wholesale items.
  3. No more than 24 hours have passed since the key was delivered.
  4. The order is not a pre-order.

You can send only one return request per order. It covers every eligible key at once — partial returns of selected keys are not possible.

When the refund is made

  • Delivered, eligible keys are refunded immediately, while the return request is processed.
  • Keys not yet delivered (delayed delivery) are returned separately, as soon as they are delivered, and refunded at that moment.
  • Refunds go to your Kinguin balance (EUR). Check it with GET /api/v1/balance.
  • You receive an order.status webhook when the order status changes.

Errors

kindMeaning
NoKeysToReturnNo key in the order meets the requirements (e.g. all keys claimed or 24 h passed)
OrderNotSupportedThe order type cannot be returned (wholesale, pre-order)
OrderNotFoundUnknown order, or an order of another store