Kinguin dictionary - documentation nomenclature

Price and currency

Within our API system, we provide support for two types of prices: price and priceIWTR (Price I Want To Receive). The prices consists of amount (in eurocents) and currency (always "EUR") fields.

Below you will find detailed information about these fields and their usage in API requests and responses.

1. Price The price field refers to the price visible to customers on the product page (it accounts for commissions). It represents the price customers will see before making a purchase. Sample structure of the price field in JSON format:

"price": {
    "amount": 200,      // Amount in cents
    "currency": "EUR"   // Currency (always EUR)
}

2. Price IWTR The priceIWTR field specifies the price the seller will ultimately receive for sold products. Sample structure of the priceIWTR field in JSON format:

"priceIWTR": {
    "amount": 200,      // Amount in cents
    "currency": "EUR"   // Currency (always EUR)
}

📌 Notes on price and currency format:

• Prices are always provided in EUR cents to avoid floating-point precision issues.
• The minimum amount is 0 eurocents.
• The maximum amount is 1000000 eurocents.
• The currency used in the system is always euro (EUR).
• For offer creation and updates, the price field in the sent request corresponds to the IWTR price.

To determine the price from priceIWTR and vice versa, taking into account the Kinguin commission, please refer to the Commissions section for detailed calculations.

Fees and Charges Policy

This section outlines the rules and processes related to various fees and charges that may apply to merchants.

Price Change Fee

For every price change (excluding the SPA functionality), a fee will be charged. Merchants are allowed 3 free price changes per offer per day.

Fee Details:

• The fee will be charged once per day for all additional price changes beyond the free limit.
• A summary of the charges will be available in the Balance tab on the Merchant Dashboard.

Smart Pricing Assistant (SPA) Fee

Fee for using the SPA functionality is charged once a week, based on the number of offers where the SPA was active during the previous week. Merchants can use the SPA functionality for free on up to 5 offers.

Fee Details:

• The fee will be charged once per week, according to a tiered structure. More info in SPA Pricing section.
• A summary of the weekly SPA charges will be available in the Balance tab on the Merchant Dashboard.

Commissions

Commission refers to the fee charged by the platform, deducted from the final price of the product before transferring funds to the seller. This commission is included in the final price seen on Kinguin product page. The price without commission, which is the amount the seller receives for selling the product, is represented by the priceIWTR field. Commission is represented within an offer by the following field: "commissionRule": { "id": "86656332-4494-4834-87f2-1214a69ce70e", "ruleName": "KinguinBaseCommssion", "fixedAmount": 10, "percentValue": 10 } where

• id: Unique identifier for the commission rule.
• ruleName: Name or identifier of the commission rule.
• fixedAmount: Fixed amount of commission charged, if applicable.
• percentValue: Percentage value of commission charged, if applicable.

To calculate price from priceIWTR and vice versa (based on Kinguin commission), use the endpoint:

**See detailed documentation curl -X GET \ -H "Authorization: Bearer ${TOKEN}" \ -H "Content-Type: application/json" \ https://gateway.kinguin.net/sales-manager-api/api/v1/offers/calculations/priceAndCommission?kpcProductId=[kpcProductId]&price=[price]

Price and Commission Calculation Discrepancy

The system allows to calculate priceIWTR based on the final price. However, due to rounding to two decimal places, multiple distinct price values can result in the same priceIWTR. Example:Consider the following scenarios: price = 10524 -> priceIWTR = 10009 price = 10525 -> priceIWTR = 10010 price = 10526 -> priceIWTR = 10010 price = 10527 -> priceIWTR = 10011 In this example, both price values of 10525 and 10526 result in the same priceIWTR of 10010. Solution:To address this, the /priceAndCommission endpoint prioritizes priceIWTR as the primary price reference. Therefore, when a user queries this endpoint with a specific priceIWTR, the system returns the corresponding lowest price value that yields that priceIWTR after rounding. If a user queries /priceAndCommission with priceIWTR = 10010, the system will return price = 10525, as it is the lowest price that results in the desired priceIWTR after rounding. Conclusion:This approach ensures that each priceIWTR maps to a unique and predictable price value, maintaining consistency and accuracy within the system.

📌 Notes on commissions:

• also appears in the responses under the name commissionRule

Date and time

Date and time fields are represented in the format YYYY-MM-DDTHH:mm:ss.ms+0000 where +0000 is the GMT timezone. Example of a date time field: "createDate": "2021-08-31T13:00:38.914+0000"

API integration description

Kinguin API is dedicated to sellers and enables the entire sales process to be conducted comprehensively, meaning that sellers can handle all stages of the transaction, from start to finish, using only our API - from creating an offer to sending the key to the buyer.

This integration enables sellers to easily create and modify offers, effectively manage their inventory of product keys, and utilize the "declared stock approach" for accurate inventory tracking and timely delivery to customers. Additionally, sellers have the option to engage in wholesale selling, with the ability to offer discounts based on the quantity of keys purchased.

Offer creation

To create an offer use the endpoint with required productId and price fields:

**See detailed documentation curl -X POST \ -H "Authorization: Bearer ${TOKEN}" \ -H "Content-Type: application/json" \ -d '{"productId": "${PRODUCT_ID}", "price": {"amount": 2, "currency": "EUR"}}' \ https://gateway.kinguin.net/sales-manager-api/api/v1/offers response:

{
    "id": "660691850f65d000010da229",
    "productId": "60d990172adc85b8f1b1ee96",
    "name": "Forspoken EU PS5 CD Key",
    "sellerId": 1066100,
    "status": "ACTIVE",
    "block": null,
    "priceIWTR": {
        "amount": 1500,
        "currency": "EUR"
    },
    "price": {
        "amount": 1660,
        "currency": "EUR"
    },
    "commissionRule": {
        "id": "86656332-4494-4834-87f2-1214a69ce70e",
        "ruleName": "super-deal",
        "fixedAmount": 10,
        "percentValue": 10
    },
    "declaredStock": 0,
    "maxDeliveryDate": null,
    "declaredTextStock": 0,
    "reservedStock": 0,
    "availableStock": 0,
    "buyableStock": 0,
    "updatedAt": "2024-03-29T10:01:42.177+0000",
    "createdAt": "2024-03-29T10:01:41.733+0000",
    "wholesale": {
        "name": "Default",
        "enabled": true,
        "tiers": [
            {
                "discount": 0,
                "level": 1,
                "price": {
                    "amount": 1590,
                    "currency": "EUR"
                },
                "priceIWTR": {
                    "amount": 1500,
                    "currency": "EUR"
                }
            },
            {
                "discount": 0,
                "level": 2,
                "price": {
                    "amount": 1530,
                    "currency": "EUR"
                },
                "priceIWTR": {
                    "amount": 1500,
                    "currency": "EUR"
                }
            },
            {
                "discount": 0,
                "level": 3,
                "price": {
                    "amount": 1515,
                    "currency": "EUR"
                },
                "priceIWTR": {
                    "amount": 1500,
                    "currency": "EUR"
                }
            },
            {
                "discount": 0,
                "level": 4,
                "price": {
                    "amount": 1500,
                    "currency": "EUR"
                },
                "priceIWTR": {
                    "amount": 1500,
                    "currency": "EUR"
                }
            }
        ]
    },
    "sold": 0,
    "productDetails": {
        "metacritic": null,
        "region": {
            "id": 3,
            "name": "Region Free"
        },
        "platform": {
            "id": 13,
            "name": "Other"
        },
        "imageUrl": "https://static.kinguin.net/media/images/products/_111.png",
        "softwareMS": null,
        "productType": {
            "softwareMS": false,
            "prePaid": true,
            "skinsCSGO": false,
            "randomProduct": false,
            "indieValley": false,
            "nft": false,
            "businessStore": false
        },
        "marketingProductType": "GAME"
    },
    "preOrder": false,
    "sold1d": 0,
    "sold7d": 0,
    "sold30d": 0,
    "popularityBid": {
        "amount": 0,
        "currency": "EUR"
    },
    "popularityPosition": null,
    "popularity": 0.0,
    "buyButtonProbability": null,
    "buyButtonBidEnabled": true,
    "hasBuyButtonDeal": false,
    "outOfStockIn1day": null,
    "merchantType": "MERCHANT",
    "salesBoosterActivationDate": null,
    "salesBoosterRenewal": false,
    "spaActive": false,
    "favorite": null,
    "bestWholesaleOffer": null,
    "bestOffer": null
}

The optional status field in the request accepts values "ACTIVE" or "INACTIVE". If the field is not provided, it defaults to "ACTIVE".

Some products may undergo automatic system blocking. In such cases, the offer's status remain ACTIVE, but the block field will not be null or empty, indicating that the offer is unavailable for purchase by customers. For more details regarding blocked offers, please refer here.

The offer will be visible on the Kinguin product page after meeting the following criteria:

• It has an ACTIVE status.
• It is not blocked (the block field is null).
• Stock is uploaded or declared stock is available (the buyableStock field is greater than 0). For more information about buyableStock, please refer here.
• It is not a pre-order offer.
• It is not a pre-purchase offer.

📌 Notes on offer creation:

• Final price is calculated automatically by system when creating an offer based on the merchant's commission. To determine the price from priceIWTR and vice versa, taking into account the Kinguin commission, please refer to the Commissions section for detailed calculations.
• To upload a stock, the offer must be created first.
• To activate declared stock approach, the declaredStock field should be provided (this field can also be added during the offer update process).

Upfront stock upload

To upload upfront stock, the offer must first be created. The uploaded key can be a type can be in the form of text or image (base64). Allowed request mime types: "text/plain", "image/jpeg", "image/png", "image/gif"

**See detailed documentation curl -X POST \ -H "Authorization: Bearer ${TOKEN}" \ -H "Content-Type: application/json" \ -d '{"body": "key123", "mimeType": "text/plain"}' \ https://gateway.kinguin.net/sales-manager-api/api/v1/offers/${OFFER_ID}/stock response: { "id":"f64e66d5-e26c-426a-ba8b-cfeb220972ff", "productId":"${PRODUCT_ID}", "offerId":"${OFFER_ID}", "sellerId":5005408, "status":"AVAILABLE" } Stock status description:

• AVAILABLE: The key is available for immediate purchase by customers.
• DISABLED: The key is disabled and unavailable for purchase by customers.
• DISPATCHED: The key has already been delivered to the customer.
• DISPATCHING: The key is currently in the process of being delivered to the customer.
• REMOVED: The key has been removed and is no longer available for customers.
• RETURNED: The key has been returned by the customer and is no longer available for resale.

There are 4 fields describing your AVAILABLE stock: { [...] "availableStock": 2, // upfront uploaded stock "buyableStock": 22, // actual available for purchase stock "declaredStock": 20, // declared stock, not physically added to Kinguin's stock "reserverdStock": 4, // purchased stock but not yet paid or delivered - reserved keys before finalizing the transaction [...] }

📌 Notes on stock upload:

• To upload an image, send payload, where the body is base64 string.
• After purchasing a key, a key in the stock with the status AVAILABLE will automatically be delivered to the buyer and marked as DISPATCHED upon delivery.
• To upload stock after a purchase, the declaredStock field must have a value greater than 0 and the declared stock approach must be implemented by the merchant.

Key stock removal

There is no possibility to delete the key from the stock via API, you can do it manually in the Merchant Panel in the offer edition tab and this operation requires Two Factor Authentication (2FA).

Declared stock approach

The declared stock approach is an automation of the key delivery process. To fully automate this process, merchants should listen to the webhooks sent by Kinguin and respond accordingly, including delivering keys to paid orders.

Stock declaration

Declared stock You can specify the declaredStock for an offer when creating it: **See detailed documentation curl -X POST \ -H "Authorization: Bearer ${TOKEN}" \ -H "Content-Type: application/json" \ -d '{"productId": "${PRODUCT_ID}", "price": {"amount": 2, "currency": "EUR"}, "declaredStock": 100}' \ https://gateway.kinguin.net/sales-manager-api/api/v1/offers or updating an existing one: **See detailed documentation curl -i -X PATCH \ -H "Authorization: Bearer ${BEARER}" \ -H "Content-Type: application/json" \ -d '{"declaredStock": 100}' \ https://gateway.kinguin.net/sales-manager-api/api/v1/offers/${OFFER_ID}

Declared text stock

Some of our clients and sales channels require keys to be delivered in text format. To accommodate such cases effectively, it's necessary not only to track the quantity of available text stock but also to ensure the provision of this type of key upon customer request during order placement. To manage this process seamlessly, alongside specifying the quantity of available stock, ensure to set the value in the declaredTextStock field. If a customer orders a text stock (identifiable by the 'requestedKeyType=TEXT' field in webhook events), you should provide a text stock and additionally include the reservation reference via the reservationId field. The field means how much of the stock set in the declaredStock is of the text type. so its value should be lower or equal (when all all the available stock is text) than declaredStock. You can specify the declaredTextStock for an offer when creating it: **See detailed documentation curl -X POST \ -H "Authorization: Bearer ${TOKEN}" \ -H "Content-Type: application/json" \ -d '{"productId": "${PRODUCT_ID}", "price": {"amount": 2, "currency": "EUR"}, "declaredStock": 100, "declaredTextStock": 20}' \ https://gateway.kinguin.net/sales-manager-api/api/v1/offers or updating an existing one: **See detailed documentation curl -i -X PATCH \ -H "Authorization: Bearer ${BEARER}" \ -H "Content-Type: application/json" \ -d '{"declaredStock": 100, "declaredTextStock": 20}' \ https://gateway.kinguin.net/sales-manager-api/api/v1/offers/${OFFER_ID}

A fee may apply for undelivered orders due to a Cancel_Out_of_Stock alert. Fees may vary between retail and wholesale orders. Please contact your account manager for the latest pricing details.

Webhooks

Webhooks are events sent to specific URLs set by the merchant. These events are associated with changes in reservation status (for individual purchased keys). Webhooks are sent for individual keys to handle wholesale scenarios and cases where the merchant has part of the stock uploaded previously and part declared, which must be delivered after purchase.

Webhooks subscription To be able to handle the declared stock approach, setting up URLs for webhooks is required. This can be done either by sending a request: **See detailed documentation

curl -i -X POST \
  https://gateway.kinguin.net/envoy2/api/v1/subscription \
  -H 'authorization: Bearer ${BEARER}' \
  -H 'content-type: application/json' \
  -d '{
        "endpoints": {
          "reserve": "https://webhook.site/6e8ab695-872b-46a2-affe-218ac3b35c5c",
          "give": "https://webhook.site/6e8ab695-872b-46a2-affe-218ac3b35c5c",
          "cancel": "https://webhook.site/6e8ab695-872b-46a2-affe-218ac3b35c5c",
          "delivered": "https://webhook.site/6e8ab695-872b-46a2-affe-218ac3b35c5c",
          "outofstock": "https://webhook.site/6e8ab695-872b-46a2-affe-218ac3b35c5c",
          "returned": "https://webhook.site/6e8ab695-872b-46a2-affe-218ac3b35c5c",
          "reversed": "https://webhook.site/6e8ab695-872b-46a2-affe-218ac3b35c5c",
          "refunded": "https://webhook.site/6e8ab695-872b-46a2-affe-218ac3b35c5c",
          "processingpreorder": "https://webhook.site/6e8ab695-872b-46a2-affe-218ac3b35c5c",
          "offerblocked": "https://webhook.site/6e8ab695-872b-46a2-affe-218ac3b35c5c",
          "processingingame": "https://webhook.site/6e8ab695-872b-46a2-affe-218ac3b35c5c",
          "chatmessage": "https://webhook.site/6e8ab695-872b-46a2-affe-218ac3b35c5c",
          "orderprocessing": "https://webhook.site/6e8ab695-872b-46a2-affe-218ac3b35c5c"
        },
        "headers": [{"name":"X-Auth-Token", "value":"xxxx"}]
}'

or using the Merchant Panel:

The preview of the configured subscription is available at the endpoint

Each webhook request is attempted up to 3 times upon receiving a reservation status change. Subsequent attempts occur at intervals: 1st attempt is made immediatelly, 2nd attempt after 5 minutes from the last failure, 3rd after 15 minutes.

Notes on webhooks subscription:

• You can create subscription only once. You are able to modify your subscription multiple times depending on your needs.
• Please note that any modifications made to a subscription will only affect newly created webhooks. For instance, if you change the endpoint for the 'DELIVERED' event, all subsequent webhooks will be directed to the updated endpoint. However, previously queued webhooks will continue to be delivered to the old endpoint.

Webhooks description

For webhooks related to reservation status (reserve, give, cancel, delivered, returned, outofstock, refunded, reversed, processingpreorder) the body structure remains consistent, with the status field corresponding to the reservation status as outlined in the table above. { "name": "Testowe CD Key", "price": { "amount":2, "currency":"EUR" }, "priceIWTR": { "amount":2, "currency":"EUR" }, "commissionRule": {"fixedAmount":0,"percentValue":0.0,"ruleName":"Zero"}, "productId": "${PRODUCT_ID}", "offerId": "${OFFER_ID}", "status": "BUYING", "reservationId": "${RESERVATION_ID}", "availableStock": 0, "buyableStock": 0, "declaredStock": 1, "reservedStock": 1, "requestedKeyType": null, "updatedAt": "2020-03-06T15:58:49.088+0000", "popularityBid":{ "amount": 0, "currency": "EUR" } } The body structure of offerblocked webhook corresponds to the offer structure, similar to the response structure obtained when querying offer details.

The body structure of chatmessage webhook { "senderName": "name", "message": "test message", "createdAt": "2020-03-06T15:58:49.088+0000" }

The body structure of orderprocessing webhook { "orderId": "123", "productId": "321", "qtyOrdered": "20" }

Webhooks history

Merchants utilizing the declared stock approach can review the history of webhooks sent to them under the designated endpoint: **See detailed documentation

curl -X GET \
        -H "Authorization: Bearer ${TOKEN}" \
        -H "Content-Type: application/json" \
https://gateway.kinguin.net/envoy2/api/v1/requests

The body of the webhook that was sent is visible as a string in the request.toSent.body field, while the reservation ID is specified in the request.toSent.bodyId field. The number of webhook send attempts is visible in the request.deployAttempts field.

Declared stock upload

API delivering key process - description

Purchase Initiation

1. User placed an order and the reserve webhook is sent (the user has not paid for the order yet).
2. User can cancel the order - the cancel webhook is sent in this case.
3. Give webhook is sent after we receive the payment. Kinguin is trying to send the key from your stock.

Delivery process

1. After sending give webhook, Kinguin is trying to send the key from your stock.
2. If there is no stock for the offer we are sending:
   • outofstock webhook and you should deliver the stock as soon as possible,
   • processingpreorder webhook if the offer is pre-order and which informs you that you need to deliver the key in the time of game release. If you do not provide the key on the game's release date the outofstock webhook is sent.
3. Failure to deliver the key within 19 minutes will result in cancellation of the order.
4. If the key is successfully delivered to the buyer, the delivered webhook is sent.

Complaint Handling

1. If the buyer did not see the key and decided to return it we are sending returned webhook, refund the order and the key is thrown into the offer’s stock and it will be automatically delivered to the new reservation.
2. If the buyer saw the key and filed a complaint (e.g. the key is not working for him) then he opens the report and you as a merchant can chat with him in merchant’s panel (Customer Support -> Resolution Center) where you can decide to refund this key and after that you will receive a refunded webhook.

API delivering key process - implementation

1. Listen on reservation event (reservation status: BUYING) and return HTTP 200 OK
2. Listen on give event (reservation status: BOUGHT) and return HTTP 200 OK
3. Listen on outofstock event (reservation status: OUT_OF_STOCK) and return HTTP 200 OK
4. Listen on cancel event (reservation status: CANCELED) and return HTTP 200 OK
5. Upload stock after receiving outofstock event (upload to the offer or to the specific reservation)

Upload to the offer’s stock curl -X POST \ -H "Authorization: Bearer ${TOKEN}" \ -H "Content-Type: application/json" \ -d '{"body": "cd key", "mimeType": "text/plain"}' \ https://gateway.kinguin.net/sales-manager-api/api/v1/offers/${OFFER_ID}/stock Upload to the reservation. You can use this field always when you want to fully control how keys are distributed across all orders. curl -X POST \ -H "Authorization: Bearer ${TOKEN}" \ -H "Content-Type: application/json" \ -d '{"body": "cd key", "mimeType": "text/plain", "reservationId": ${RESERVATION_ID}}' \ https://gateway.kinguin.net/sales-manager-api/api/v1/offers/${OFFER_ID}/stock

6. Listen on delivered event (reservation status: DELIVERED) and return HTTP 200 OK

Block on the offer

Offers on our platform may encounter situations necessitating temporary or permanent blocking due to various reasons. To address these diverse scenarios comprehensively, our system incorporates multiple types of blocks. Blocks rare categorized as follows:

Automatic Blocks These blocks are automatically set during offer creation and are related to the type of product for which the offer is created. Admin-Set Blocks Blocks manually set by Kinguin administrators. Sales-Related Blocks Blocks associated with offer sales, such as blocks due to reported issues with the offer or undelivered keys.

Block on an offer is reflected in the block field within the offer response. Below, we provide an example JSON snippet illustrating an offer along with the block field. { "id": "65d36ed879c2842175958bb2", "name": "XBOX Game Pass Core 3 Months Subscription Card", "status": "ACTIVE", "block": "MANUAL_VERIFICATION_PREPAID_PRODUCT", ... }

Description of automatic blocks that requires manual verification by our Customer Support:

Offer deactivation

In our system, there is no hard delete option available for offers. To deactivate an offer, you must set its status to INACTIVE. **See detailed documentation curl -i -X PATCH \ -H "Authorization: Bearer ${BEARER}" \ -H "Content-Type: application/json" \ -d '{"status": "INACTIVE"}' \ https://gateway.kinguin.net/sales-manager-api/api/v1/offers/${OFFER_ID}

Key returns and complaints

Returns Buyers may return a key and receive an immediate refund only if they haven't claimed the key. In such cases, a returned webhook is sent after the buyer's action.

Complaints In case a buyer has concerns or issues regarding a purchased key, they have the option to open a report. This action initiates the creation of a case in the Resolution Center, where the seller and the buyer can work towards resolving the matter between themselves or escalate it to the customer support team if necessary. In the merchant panel, this functionality can be accessed through the Customer Support tab -> Resolution Center.

Wholesale

Offers can be configured to be sold wholesale. There are four tiers available, each offering decreasing prices based on the quantity of keys purchased: Level 1: 0 to 10 pcs Level 2: Above 10 to 20 pcs Level 3: Above 20 to 50 pcs Level 4: Above 50 pcs

To enable an offer for wholesale, its enabled field must be set to true and sell tiers need to be defined (level + discount that represents a percentage discount off the offer's IWTR price). **See detailed documentation curl -X POST \ -H "Authorization: Bearer ${TOKEN}" \ -H "Content-Type: application/json" \ -d '{ "productId": "${PRODUCT_ID}", "price": {"amount": 200, "currency": "EUR"}, "wholesale": { "enabled": true, "name": "custom", "tiers": [ {"level": 1,"discount": 3}, {"level": 2,"discount": 4}, {"level": 3,"discount": 5}, {"level": 4,"discount": 7} ] } }' \ https://gateway.kinguin.net/sales-manager-api/api/v1/offers response

{
    "id": "660691850f65d000010da229",
    [ ... ]
    "priceIWTR": {
        "amount": 200,
        "currency": "EUR"
    },
    "price": {
        "amount": 230,
        "currency": "EUR"
    },
    "wholesale": {
        "name": "custom",
        "enabled": true,
        "tiers": [
            {
                "discount": 3,
                "level": 1,
                "price": {
                    "amount": 206,
                    "currency": "EUR"
                },
                "priceIWTR": {
                    "amount": 194,
                    "currency": "EUR"
                }
            },
            {
                "discount": 4,
                "level": 2,
                "price": {
                    "amount": 196,
                    "currency": "EUR"
                },
                "priceIWTR": {
                    "amount": 192,
                    "currency": "EUR"
                }
            },
            {
                "discount": 5,
                "level": 3,
                "price": {
                    "amount": 192,
                    "currency": "EUR"
                },
                "priceIWTR": {
                    "amount": 190,
                    "currency": "EUR"
                }
            },
            {
                "discount": 7,
                "level": 4,
                "price": {
                    "amount": 186,
                    "currency": "EUR"
                },
                "priceIWTR": {
                    "amount": 186,
                    "currency": "EUR"
                }
            }
        ]
    },
   [ ... ]
}

To disable wholesale for offer, please set wholesale enabled attibute to false: **See detailed documentation curl -i -X PATCH \ -H "Authorization: Bearer ${BEARER}" \ -H "Content-Type: application/json" \ -d '{"wholesale":{"enabled":false,"name":"dontSell"}}' \ https://gateway.kinguin.net/sales-manager-api/api/v1/offers/${OFFER_ID}

📌 Notes on wholesale:

• The wholesale is enabled by default but without discounts.
• Wholesale tiers can be set while creating or updating an offer.
• Products such as Windows and MS Office cannot be sold wholesale.

Pre-order

Pre-orders are special products with a predetermined release date specified in advance. These products typically include 'PRE-ORDER' in their name. Upon purchase of such an offer, the processingpreorder webhook is sent to the seller. When the release date is reached, the sold keys must be promptly delivered.

Pre-purchase

Pre-purchase offers are a type of offer that can be created for any product that is not a pre-order. This offer allows setting a maximum delivery date by which the seller commits to deliver the keys. To create such an offer, simply include the maxDeliveryDate field in the request. **See detailed documentation curl -X POST \ -H "Authorization: Bearer ${TOKEN}" \ -H "Content-Type: application/json" \ -d '{"productId": "${PRODUCT_ID}", "price": {"amount": 2, "currency": "EUR", "maxDeliveryDate":"2025-08-30"}}' \ https://gateway.kinguin.net/sales-manager-api/api/v1/offers 📌 Notes on pre-purchase:

• Because the key for the offer is not delivered immediately, this offer is not visible on the product page; instead, it is available in the Wholesale tab in the Merchant Panel.
• It's not possible to convert a pre-purchase offer into a standard offer. To create a standard offer, the pre-purchase offer must first be deactivated, and then a new offer can be created.

Smart Pricing Assistant (SPA)

The Smart Pricing Assistant (SPA) is a feature designed to empower merchants by automating the process of adjusting offer prices. With SPA, merchants can optimize their pricing strategies effortlessly, ensuring competitiveness and profitability. This chapter provides an in-depth look into the main features and processes of the SPA tool, along with examples of how to use it effectively.

Key features of SPA

Automated Price Adjustments SPA allows merchants to automate the adjustment of their offer prices based on predefined criteria. By utilizing the provided APIs, merchants can set specific conditions under which prices should be modified. SPA then continuously monitors these conditions and applies the necessary price changes, freeing merchants from the manual price adjustment process.

Precise Control Merchants have full control over the price adjustment parameters. These parameters include:

• the key cost
• minimum profit
• maximum profit

Real-time Updates SPA operates in real-time, ensuring that price adjustments are promptly applied whenever the predefined conditions are met. This guarantees that merchants remain competitive and responsive to market dynamics without delays.

SPA Pricing Logic

The Smart Pricing Assistant (SPA) operates on a sophisticated logic designed to optimize the position of a merchant's offer on Kinguin. SPA's primary objective is to enhance the competitiveness and profitability of the merchant by automating price adjustments based on market conditions. The key pricing principles of SPA are outlined below.

1. Competitive Positioning SPA aims to position the merchant's offer as competitively as possible. It achieves this by pricing the offer just 0,01 Euro below the competing offer.

   • Outbidding Competitive Price If a competitive offer is found, SPA will automatically reduce the price of the offer to be 0.01 Euro lower than the competitive price, as long as this reduction still falls within the minimum price set by the user.

   • No Outbidding Competitive Price If the minimum price set by the user is higher than the found competitive offer but lower than the current user price, SPA will increase the user's price by 0,01 Euro to make it 1 cent lower than the offer that is one position below. This adjustment is made to maintain the current offer position while obtaining a higher price for it.

2. Best Possible Position SPA always strives to secure the best available position for the merchant's offer. However, this positioning is subject to certain constraints: the key cost and the minimum profit amount defined by the merchant.

3. Flexibility If the merchant's offer cannot attain the first position due to higher key costs or minimum profit requirements, SPA adjusts the offer's price to be 0.01 Euro below the next available position. This flexibility ensures that the offer remains competitive while adhering to the merchant's pricing strategy.

Managing SPA

Activating SPA for Offers SPA can be activated on a single offer up to 5 times per day. To activate the Smart Pricing Assistant for a specific offer, the following API call can be used: **See detailed documentation

curl -X POST \
    -H "Authorization: Bearer ${TOKEN}" \
    -H "Content-Type: application/json" \
    -d '[{"offerId":"63e21a36814762653336ba8f","keyCost":300,"minProfitAmount":40,"minPriceIWTR":{"amount":340,"currency":"EUR"}, "maxProfitAmount":90}]' \
  https://gateway.kinguin.net/pizzaportal/api/v1/spa/offers

Request allows to activate SPA in more than 1 offer at the time (array of offers in a body request). Once activated, SPA will automatically adjust the offer's price based on the defined criteria. Detailed description of the body request:

Updating Minimum Price Merchants can update the minimum price, key cost, and minimum profit amount for an offer with the following API call: curl -X PUT \ -H "Authorization: Bearer ${TOKEN}" \ -H "Content-Type: application/json" \ -d '{"minPriceIWTR":{"amount":344,"currency":"EUR"},"keyCost":300,"minProfitAmount":44}' \ https://gateway.kinguin.net/pizzaportal/api/v1/spa/offers/${OFFER_ID} This API call allows merchants to modify the price adjustment parameters, thereby influencing SPA's automated pricing decisions. Detailed description of the body request:

Deactivating SPA for an Offer To deactivate SPA for a specific offer, merchants can use the following API call: curl -X DELETE \ -H "Authorization: Bearer ${TOKEN}" \ -H "Content-Type: application/json" \ https://gateway.kinguin.net/pizzaportal/api/v1/spa/offers/deactivate/${OFFER_ID}"

SPA Technical Behavior Overview

--> SPA statuses

Smart Pricing Assistant operates based on a set of internal states that determine whether the functionality is actively managing the offer’s price. There are three possible SPA statuses: ACTIVE – SPA is actively running and updating the offer's price. PAUSED – SPA is temporarily not running when the offer becomes non-buyable (e.g., inactive status, no stock, or the offer is blocked). INACTIVE – SPA is disabled for the offer.

SPA Activation Rules:

• SPA can only be activated on offers that are both active and buyable.
• Upon activation, the SPA status is immediately set to ACTIVE.

Automatic Status Transitions:

• The SPA status is automatically changed to PAUSED if the offer becomes non-buyable (the offer status changes to INACTIVE or blocked or there is no available stock (buyableStock = 0).
• If an offer in PAUSED state becomes buyable again, the SPA status will automatically switch back to ACTIVE.

Manual Deactivation:

• SPA can be deactivated only manually by the seller.

SPA Billing Exclusion: Offers that remain non-buyable and PAUSED for the entire billing period are excluded from the weekly Smart Pricing Assistant fee calculation.

--> SPA price changes

The SPA bot automatically adjusts prices in response to several actions that occur on offers of a specific product.

Price Decrease

• The SPA should decrease the price by 0.01 EUR from the current lowest price, provided that the minPrice allows it.

Price Increase

• The SPA should increase the price so that the offer is 0.01 EUR cheaper than the next offer in the list.
• Price increase can be performed automatically no more frequently than once per hour.

SPA Bot Trigger

• The bot must find another offer to adjust the new price.
• The price change is triggered by: -- SPA activation. -- When the SPA is activated on an inactive offer, and the offer becomes active. -- When the price of the other offer on product page changes. -- When the min and max price in the SPA configuration changes.
• SPA activation triggers an immediate price change only when the SPA settings allow for an automatic price decrease. For example: -- (offer1: 5.00 EUR, offer2: 5.01 EUR) If offer2 sets its minPrice to 4.98 EUR, SPA will automatically decrease offer2's price to 0.01 EUR lower than the current lowest price (offer1: 5.00 EUR, offer2: 4.99 EUR). -- (offer1: 5.00 EUR, offer2: 5.01 EUR) If offer2 sets its minPrice to 5.20 EUR, SPA will not take any action, and the price will remain unchanged (offer1: 5.00 EUR, offer2: 5.01 EUR).

Smart Pricing Assistant (SPA) Pricing

Fees Related to the Use of Smart Pricing Assistant (SPA) Functionality Fees for using the Smart Pricing Assistant (SPA) functionality are charged once a week based on the number of offers on which the SPA functionality was active during the previous week.

When is the SPA functionality considered active? The SPA functionality is considered active when:

• SPA is activated on the offer.
• The offer has status ACTIVE.
• The offer has buyable stock > 0.
• The offer is not blocked.

Fee Collection Schedule The fee is charged once a week, every Monday at 00:00 UTC.

Fee Structure Fees for using the SPA functionality are charged according to the following tier structure, depending on the number of offers where the functionality was active:

Examples

Scenario 1:

• Throughout the week, the seller activates SPA on 5 active offers.
• The seller then deactivates SPA on all offers.
• Later on, the seller reactivates SPA on exactly the same offers. Result: Over the past week, SPA was active on only 5 offers because the same offers were reactivated. No fee will be charged because activation of SPA on up to 5 offers is free of charge.

Scenario 2:

• Throughout the week, the seller activates SPA on 5 active offers.
• The seller then deactivates SPA on all offers.
• Later on, the seller activates SPA on different active offers (not the same as before). Result: Over the past week, SPA was active on a total of 10 different offers. The fee will be charged according to the current pricing.

Scenario 3:

• Throughout the week, the seller activates SPA on 10 different active offers.
• The seller then deactivates SPA on all offers. Result: Over the past week, SPA was active on a total of 10 different offers, even though on the billing day no offers have SPA enabled. The fee is charged based on the number of offers with active SPA during the week, regardless of whether SPA is active on the billing day. The fee will be charged according to the current pricing.

📌 Notes on SPA pricing:

• Activating SPA on up to 5 offers is free of charge.
• All fees are automatically charged based on the number of active offers in the system, and the amounts are collected once a week at the established time.

Sales Booster

Sales Booster is an innovative tool tailored for merchants who seek enhanced visibility on the Kinguin’s product page buy button despite price-related limitations. This chapter delves into the key features and processes of the Sales Booster, demonstrating how merchants can strategically leverage this tool to increase their presence and boost sales on the platform.

Visibility Enhancement Sales Booster is designed to give merchants an opportunity to stand out on Kinguin, even when they can't compete purely on price. By utilizing the provided endpoints, merchants can strategically bid for better positioning on the buy button, allowing them to catch the attention of potential customers.

Strategic Bidding Merchants have the flexibility to place bids for improved positioning based on their marketing strategy and budget. This enables them to allocate resources effectively to enhance their offer’s visibility.

Managing Sales Booster

Requesting Visibility Boost To enhance the visibility of an offer using the Sales Booster, merchants can send a POST request to the following endpoint: **See detailed documentation curl -X POST \ -H "Authorization: Bearer ${TOKEN}" \ -H "Content-Type: application/json" \ -d '{"maxBid": 10, "salesBoosterRenewal": true}' \ https://gateway.kinguin.net/sales-manager-api/api/v1/offers/{OFFER_ID}/popularity This API call allows merchants to strategically place bids to improve their offer's visibility on the buy button. The offer ID should be replaced with the corresponding offer's identifier.

Checking Position and Bid Impact Merchants can assess the potential impact of their bid on their offer's position using the following GET request: curl -X GET \ -H "Authorization: Bearer ${TOKEN}" \ -H "Content-Type: application/json" \ https://gateway.kinguin.net/sales-manager-api/api/v1/offers/{OFFER_ID}/position?bid={BID}&price={PRICE} This API call provides merchants with insights into how their offer's position would change based on the specified bid and price parameters. It's a valuable tool to make informed decisions regarding bid amounts.

Steam Accounts

Besides selling keys on Kinguin, there is also the option to sell Steam accounts. To unlock this possibility, please contact your account manager. For such products, the product page displays the following information for the buyer: This is not a product key. A NEW ACCOUNT will be created for you, and the purchased content will be available there.

In-game Goods

Kinguin platform supports the listing and sale of in-game products, including items and in-game currency. These products cater to gamers who wish to buy or sell virtual goods directly related to specific games. To begin selling in-game products, you must first contact your account manager to unlock this feature on your account.

Buying and Delivery Process

The purchase and delivery workflow for offers on our platform involves several steps, primarily involving manual actions on the Kinguin site. Here’s a detailed overview of the process:

1. Order Payment and Notification

• When a user completes the payment for a product, the system generates a notification.
• This notification is sent via email to the seller and is also visible in the “Sales” tab on the merchant dashboard.

2. Creating a Communication Channel

• For each order, a chat channel is created between the buyer and the seller.
• This chat is used to discuss and finalize the delivery method, if one is required.

3. Proof of Delivery

• After the delivery method is agreed upon and the transaction is completed, the seller must provide proof of delivery.
• This proof is submitted as an attachment in the chat channel between the buyer and seller.

4. Order Closure

• Once the proof of delivery is provided, the order is reviewed.
• The order is then marked as DELIVERED and closed.

This process ensures that each transaction is handled with transparency and efficiency, facilitating effective communication between buyers and sellers and ensuring that products are delivered as promised.

Managing In-game offers

Create an in-game offer To create an offer, you need to send a request with specific required parameters for in-game goods.

curl -X POST \
        -H "Authorization: Bearer ${TOKEN}" \
        -H "Content-Type: application/json" \
        -d '{
               "productId": "66d8320d77a097501e74a356",
                "price": {
                    "amount": 200, // price for the quantity specified in minQuantity
                    "currency": "EUR"
                },
                "declaredStock": 999999999,
                "status": "ACTIVE",
                "deliveryMethods": [
                    "FACE_TO_FACE"
                ],
                "minQuantity": 1000, // the price field corresponds to this quantity
                "description": "Short description.",
                "deliveryTime": "2h"
              }' \
   https://gateway.kinguin.net/sales-manager-api/api/v1/offers

Detailed description of the body request:

Update an in-game offer curl -i -X PATCH \ -H "Authorization: Bearer ${BEARER}" \ -H "Content-Type: application/json" \ -d '{"declaredStock": 1000000}' \ https://gateway.kinguin.net/sales-manager-api/api/v1/offers/${OFFER_ID}

SANDBOX environment

To create a sandbox account, proceed with the same steps like for production, using https://sandbox.kinguin.net. To use API sandbox endpoints please use https://gateway.sandbox.kinguin.net e.g. curl -X POST \ -H "Authorization: Bearer ${TOKEN}" \ -H "Content-Type: application/json" \ -d '{"productId": "${PRODUCT_ID}", "price": {"amount": 2, "currency": "EUR"}}' \ https://gateway.sandbox.kinguin.net/sales-manager-api/api/v1/offers

Checkout SDK implementation guide

Follow the guide below to implement and configure checkout SDK on your website and start accepting payments via our checkout flow. The SDK automatically detects user's device and browser and starts the checkout flow in an iframe if supported or in a new browser window if not.

If you would like to implement this SDK on your website, please contact us to discuss the details.

Prerequisites

• the SDK must be initialized when all product variants are available for selection on your website
• each product element must have a common selector (productElement class by default)
• each product element must have an attribute (data-product by default) with a product URL linking to the respective product page in our store
• there must be an empty wrapper element (identified by kinguinIframeWrapper ID by default) which will hold the injected iframe.
• your server must not use x-frame-options header with SAMEORIGIN value. Instead, you should use Content-Security-Policy header with frame-src directive allowing our domain (https://www.kinguin.net). Without doing that, our checkout will not be able to load in an iframe on your website. If you don't use other directives in the CSP header, you can use the header below: Content-Security-Policy: frame-src https://www.kinguin.net;

SDK updates

The SDK might be occasionally updated to provide the best possible experience. To ensure that you are using the latest version and all functionalities work properly, please use the script URL provided in this documentation. You will be informed by our team in case a new version is released.

Include the Checkout SDK Script

To use the SDK on your website, you need to include the following script tag in the head section of your HTML document:

<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Example HTML< /title>
<script defer src="https://static.kinguin.net/checkout/sdk/sdk-1.2.0.min.js">< /script>
</head>

The defer attribute ensures that the script is loaded and executed after the HTML document has been parsed, preventing potential rendering issues.

Initializing the SDK

Once your products are visible and ready to be selected, you should initialize the SDK using the function below, which will add click handlers to the product elements and handle opening the iframe or new browser window upon selection.

To initialize the SDK, use the function below:

window.kinguinCheckoutSDK.init();

In the HTML example below, the SDK is initialized after DOM content has loaded.

<body>
  <script>
    document.addEventListener('DOMContentLoaded', function () {
      window.kinguinCheckoutSDK.init();
    });
  < /script>
</body>

Please remember that you must initialize the SDK once all of your product elements are already in the DOM, as otherwise the event handlers will not be added.

Configuring the SDK

You can customize some of the options by passing a config object to the init function. The available options are listed below:

Example initialization with provided configuration object:

window.kinguinCheckoutSDK.init({
  wrapperSelector: '#myIframeWrapper',
  productsSelector: '.myProductElement',
  productUrlAttribute: 'data-product-url',
  iframeId: 'myCheckoutIframe',
  iframeWidth: '80%',
  iframeHeight: '700px',
  popupWidth: 900,
  popupHeight: 1000,
  translations: {
    popupOpenFail: 'Window could not be opened, please try again.',
  },
  discount: 'test123',
  language: 'de',
  currency: 'USD',
  email: 'test@test.com'
});

You can also pass fewer options instead of the whole object:

window.kinguinCheckoutSDK.init({
  wrapperSelector: '#myIframeWrapper',
  productsSelector: '.myProductElement',
  productUrlAttribute: 'data-product-url',
  currency: 'USD',
});

Example HTML with the script and required elements

  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Example HTML< /title>
    <script
      defer
      src="https://static.kinguin.net/checkout/sdk/sdk-1.2.0.min.js"
    >< /script>
  </head>
  <body>
    <div id="kinguinIframeWrapper"></div>
    <div
      class="productCard"
      data-product="https://www.kinguin.net/category/12345"
    >
      Product 1
    </div>
    <div
      class="productCard"
      data-product="https://www.kinguin.net/category/67890"
    >
      Product 2
    </div>
    <script>
      document.addEventListener('DOMContentLoaded', function () {
        window.kinguinCheckoutSDK.init({
          productsSelector: '.productCard',
        });
      });
    < /script>
  </body>
</html>