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.
| Resource | Link |
|---|---|
| API Reference | https://www.kinguin.net/dev-portal/esa-documentation |
| OpenAPI specification | https://www.kinguin.net/services/esa/api/info |
| Environment | API base URL | Website |
|---|---|---|
| Sandbox | https://gateway.sandbox.kinguin.net/esa | https://sandbox.kinguin.net |
| Production | https://gateway.kinguin.net/esa | https://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.
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"| Status | When |
|---|---|
| 401 Unauthorized | The API key is missing or invalid |
| 403 Forbidden | The 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) |
Both versions are live and share the same data. The main difference is the product identifier used when creating orders:
| v1 | v2 | |
|---|---|---|
| Product identifier in orders | kinguinId (integer) | productId (string) |
| Product list | GET /api/v1/products — deprecated | GET /api/v2/products |
| Single product | GET /api/v1/products/{kinguinId} | GET /api/v2/products/{productId} |
| Create order | POST /api/v1/order | POST /api/v2/order |
| Order details / list | GET /api/v1/order/{orderId}, GET /api/v1/order | same 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.
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.
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.
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".
| Setting | Value |
|---|---|
| Limit | 2000 RPM |
| Period | 60 seconds |
| HTTP methods counted | POST, PUT, DELETE, PATCH |
| Host | gateway.kinguin.net |
| Response when exceeded | 429 Too Many Requests |
Requests over the limit may be rejected or delayed. Design your integration to stay below it:
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 | HTTP status | Typical cause | Suggested action |
|---|---|---|---|
| ConstraintViolation | 400, 422 | Invalid request (missing field, qty out of range, too many items) | Fix the request |
| Authorization | 401, 403 | Invalid key, forbidden operation, IP not whitelisted | Check the key / whitelist |
| InsufficientBalance | 422 | Not enough balance | No order is created. Top up your balance, then retry |
| ProductUnavailable | 422 | See reason | See table below |
| Preorder | 422 | Pre-order rules violated | See Pre-orders |
| ProductNotFound | 404 | Unknown product, or the product is currently out of stock | Hide it from your storefront — see Out of stock |
| OrderFailed | 500 | Order could not be placed | Retry later; contact support if persistent |
| OrderExternalNotUnique | 409 | The orderExternalId has already been used in your account | Use a new orderExternalId, or — when retrying after a timeout — fetch the existing order by orderExternalId |
| OrderNotFound | 404 | Unknown order | Check orderId |
| OrderNotSupported | 422 | Operation not supported for this order (e.g. returning wholesale) | — |
| NoKeysToReturn | 422 | Nothing eligible to return | — |
| Http, HttpClient, Error | 4xx, 5xx | Unexpected errors | Retry with backoff; contact support if persistent |
HTTP 429 Too Many Requests means the rate limit was exceeded.
| reason | Meaning | Suggested action |
|---|---|---|
| NoStock | Not enough quantity (or text quantity with keyType: "text") | Mark out of stock / lower qty |
| NoOffers | No offers, or the given offerId no longer exists | Mark out of stock / refresh offers |
| InvalidPrice | Your price is below the current price | Refresh the price, re-check your margin |
| OfferRequired | offerId needed (wholesale) | Add offerId |
| WholesaleNotAvailable | Wholesale not possible for this offer/quantity | Pick another offer / lower qty |
| NoTier | No wholesale tier for the quantity | Adjust qty |
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 (X-Event-Name) | Triggered when |
|---|---|
| product.update | Product data changed, stock or price changed, the product went out of stock, or a new offer became available |
| product.update.bulk | The same changes as product.update, delivered for many products in a single request |
| order.status | An order's status changed |
| order.complete | An order has been completed |
| Header | Value |
|---|---|
| X-Event-Name (always) | Event name |
| X-Event-Secret | The secret you configured — verify it on every request |
| Content-Type | application/json |
Do not use any header that is not documented in the table above in your integration.
{
"kinguinId": 1949,
"productId": "5c9b5f6b2539a4e8f172916a",
"qty": 845,
"textQty": 845,
"totalQty": 1290,
"cheapestOfferId": ["611222acff9ca40001f0b020"],
"updatedAt": "2020-10-16T11:24:08.015+00:00"
}| Field | Type | Description |
|---|---|---|
| kinguinId | int | Product ID (v1) |
| productId | string | Product ID (v2) |
| qty | int | Quantity of the cheapest offer(s) — same meaning as product qty |
| textQty | int | Text-serial quantity of the cheapest offer(s) |
| totalQty | int | Quantity across all offers — same meaning as product totalQty |
| cheapestOfferId | string[] | Cheapest offer IDs |
| updatedAt | string | Change 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).
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.
{
"orderId": "PHS84FJAG5U",
"orderExternalId": "AL2FEEHOO2OHF",
"status": "completed",
"updatedAt": "2020-10-16T11:24:08.025+00:00"
}{
"orderId": "PHS84FJAG5U",
"orderExternalId": "AL2FEEHOO2OHF",
"updatedAt": "2020-10-16T11:24:08.025+00:00"
}| Field | Type | Description |
|---|---|---|
| orderId | string | Kinguin order ID |
| orderExternalId | string | null | Your order reference; null if the order was created without it |
| updatedAt | string | Completion 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.
When you order without an offerId, Kinguin picks the cheapest offer for you. When you pass offerId, you buy from that specific offer.
| Field | Where | Meaning |
|---|---|---|
| kinguinId | product | Integer product ID, used by v1 orders |
| productId | product | String product ID, used by v2 orders |
| offers[].offerId | product | Offer ID; required for wholesale orders, optional otherwise |
| cheapestOfferId[] | product, webhook | IDs of all offers sharing the lowest price |
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.
| Field | Meaning |
|---|---|
| qty | Quantity of the cheapest offer(s) (those listed in cheapestOfferId) |
| textQty | Text-serial part of qty |
| totalQty | Quantity across all offers |
| price | Price of the cheapest offer, EUR |
| cheapestOfferId[] | IDs of all offers sharing the lowest price |
| offersCount | Number 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.
| Field | Meaning |
|---|---|
| qty | Total quantity of keys available for this offer |
| textQty | Text-serial part of this offer's qty |
| availableQty | Physical quantity of keys uploaded to Kinguin, independent of the quantity declared in the offer |
| availableTextQty | Text-serial part of availableQty |
| price | Price of this offer, EUR |
| wholesale | Wholesale 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.
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
}
}| Field | Meaning |
|---|---|
| _embedded.products[] | Products on the current page |
| page.totalElements | Total number of products matching the filters |
| page.totalPages | Total number of pages |
| page.number | Current page number |
| page.size | Page size (limit) |
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"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.

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.
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"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"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.
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).
POST /api/v2/order (uses productId)
POST /api/v1/order (uses kinguinId)| Field | Required | Description |
|---|---|---|
| products[] | yes | 1–10 items |
| products[].productId (v2) / kinguinId (v1) | yes | Product identifier |
| products[].qty | yes | 1–9 for regular orders; up to 1000 for wholesale |
| products[].price | yes | Maximum unit price in EUR you accept. Cannot be lower than the current cheapest price. |
| products[].offerId | no | Buy from a specific offer. If omitted, the cheapest offer is used. Required for wholesale. |
| products[].keyType | no | text — deliver only text serials. See Text keys. |
| orderExternalId | no | Your own order reference, unique within your account. Strongly recommended. |
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.
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.
| Field | Meaning |
|---|---|
| orderId | Kinguin order ID — use it for keys, returns and lookups |
| orderExternalId | Your reference |
| status | Order status |
| totalPrice | Total order price, EUR |
| requestTotalPrice | Total calculated from the price values you sent, EUR |
| paymentPrice | Balance actually charged, EUR |
| products[].keys[] | Per-key id and status |
| Status | Meaning |
|---|---|
| processing | Order created, keys are being delivered |
| completed | All keys delivered — you can download them |
| canceled | Order could not be fulfilled |
| refunded | Keys were returned and the balance refunded |
Each key in products[].keys[] has one of: PENDING, PROCESSING, DELIVERED, RETURNED, REFUNDED, CANCELED.
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.
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.
There is no dry-run endpoint — the order request itself is the authoritative check. Recommended pattern:
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.
GET /api/v2/order/{orderId}/keys?page=1&limit=100curl -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:
| Field | Meaning |
|---|---|
| id | Key identifier |
| name | Product name |
| type | text/plain, image/jpeg, image/png or image/gif |
| serial | The key. Base64-encoded for image types. |
| kinguinId, productId, offerId | Origin 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).
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:
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.
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.
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.
A pre-order is a product with isPreorder: true sold before its releaseDate. Keys are delivered after release.
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.
Wholesale lets you buy larger quantities (10–1000) of a single offer at tiered prices.
| Level | Quantity |
|---|---|
| 1 | 10+ |
| 2 | 50+ |
| 3 | 100+ |
| 4 | 500+ |
"wholesale": {
"enabled": true,
"tiers": [
{
"level": 1,
"price": 5.5
},
{
"level": 2,
"price": 5.4
},
{
"level": 3,
"price": 5.3
},
{
"level": 4,
"price": 5.2
}
]
}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
}
]
}'When a wholesale order cannot be placed, you get kind: "ProductUnavailable" with a structured reason:
| reason | Meaning | What to do |
|---|---|---|
| OfferRequired | offerId missing for a quantity above the regular limit | Add offerId |
| WholesaleNotAvailable | Wholesale is not enabled for this offer, or the quantity cannot be served | Choose another offer or lower the quantity |
| NoTier | No tier matches the quantity | Adjust the quantity |
| InvalidPrice | price lower than the tier price | Use the correct tier price |
| NoStock | Not enough stock | Lower the quantity |
Always branch on kind and reason, never on the human-readable detail text — its wording may change.
POST /api/v2/order/{orderId}/keys/returnThe 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" }
]A key can be returned only when all of the following are true:
You can send only one return request per order. It covers every eligible key at once — partial returns of selected keys are not possible.
| kind | Meaning |
|---|---|
| NoKeysToReturn | No key in the order meets the requirements (e.g. all keys claimed or 24 h passed) |
| OrderNotSupported | The order type cannot be returned (wholesale, pre-order) |
| OrderNotFound | Unknown order, or an order of another store |