Automate your stock with "Declared Stock"

The "Declared Stock" feature allows you to declare the number of keys you have for particular product without placing the keys to Eneba stock.

During the purchase process, Eneba.com will call your system twice. The first call will ask you to reserve the keys for a specific order - a Reservation request. The second one will ask you to provide the purchased keys, called a Provision request.

Example

You create an auction with 10 keys and using the “Declared Stock” feature declare 50 keys. This means that Eneba.com will attempt to sell 60 keys in total. First, the platform will sell 10 existing keys, then will use the "Declared Stock" feature to retrieve 50 keys more. If you create an auction with no keys and with the "Declared Stock" feature declare that you have 50 keys, then Eneba.com will attempt to retrieve those 50 keys and sell them.

Important

Sequence diagram

Following sequence diagram displays the interaction between the Buyer, Eneba, and Merchant when using the "Declared Stock" feature. This example illustrates the successful communication between Eneba and Merchant when a purchase is made.

1. Requirements

To use this feature you need to register two API callbacks with types:

• DECLARED_STOCK_RESERVATION
• DECLARED_STOCK_PROVISION

Please read more on related mutations/queries: P_registerCallback, P_removeCallback, P_apiCallbacks.

You also need to activate the "Declared Stock" feature in the production, please read more on P_enableDeclaredStock mutation.

Optionally, you may want to register the DECLARED_STOCK_CANCELLATION callback, this way you will be able to receive a callback when the order gets canceled.

Optionally, you may also register the DECLARED_STOCK_FAILED_REQUEST callback to be notified whenever Eneba is unable to process one of your Reservation or Provision responses. See the Failed request callback below.

2. Callback payloads

Every request from the Eneba.com side will be authenticated by the Authorization header using the Bearer type and value, submitted when registering the API callback by P_registerCallback mutation.

Authorization: Bearer {P_API_Callback:authorization value}

Reservation

The system will make one request with a payload below to the Reservation endpoint with a 120s timeout. In case of error, the buyer will be informed about the unavailable stock.

Request

Callback fields:

Auction fields:

Example:

{
  "action": "RESERVE",
  "orderId": "6ce660cc-4abe-11ed-b878-0242ac120002",
  "originalOrderId": null,
  "auctions": [
    {
      "auctionId": "6ce664fa-4abe-11ed-b878-0242ac120002",
      "keyCount": 2,
      "price": {
        "amount": 1500,
        "currency": "EUR"
      }
    }
  ]
}

Response

By successfully responding (HTTP status 200) to the Reservation request with the payload structure below, you indicate that you can fully fulfill the reservation.

Response fields:

Example:

{
  "action": "RESERVE",
  "orderId": "6ce660cc-4abe-11ed-b878-0242ac120002",
  "success": true
}

Provision

The system will make three attempts with a 5s sleep interval and 120s timeout for you to respond. In case of final failure, the order will be canceled. Example:

• Request 1: Fails immediately
• Wait time: 5 seconds
• Request 2: Fails after timeout (120 seconds)
• Wait time: 5 seconds
• Request 3: Fails
• Order gets cancelled

Request

Callback fields:

Example:

{
  "action": "PROVIDE",
  "orderId": "6ce660cc-4abe-11ed-b878-0242ac120002",
  "originalOrderId": null
}

Response

The following structure will be expected in the successful (HTTP status 200) response to the Provision request.

Auction fields:

Key fields:

Example:

{
  "action": "PROVIDE",
  "orderId": "6ce660cc-4abe-11ed-b878-0242ac120002",
  "success": true,
  "auctions": [
    {
      "auctionId": "6ce664fa-4abe-11ed-b878-0242ac120002",
      "keys": [
        {
          "type": "TEXT",
          "value": "QS8ND-G0W76-BTSQO-WAAJA-6LCD3"
        },
        {
          "type": "IMAGE",
          "value": "HwcqeNQhr1EfdJoHxko+ymjzBta/ipV6r9sigAAAABJRU5ErkJggg==",
          "filename": "Half-Life 3"
        }
      ]
    }
  ]
}

Cancellation

When a user or a system cancels the order, a cancellation callback will be issued informing you to release the keys for the specific order. The system will make two attempts with a 5s sleep interval and 60s timeout for you to respond.

Request

Callback fields:

Example:

{
  "action": "CANCEL",
  "orderId": "6ce660cc-4abe-11ed-b878-0242ac120002"
}

Response

No response body is expected. Successful (HTTP status 200) response confirms the cancellation.

Failed request

After every failed Reservation or Provision attempt, Eneba sends a notification to your registered failed-request endpoint describing what went wrong with that attempt — for example, an unreachable endpoint, a non-200 status, a malformed or invalid response body, or a "success": false response.

This callback is informational only: it does not change the outcome of the order, and Eneba does not retry it. Each failed attempt produces its own notification (including each Provision retry). To receive it, register the DECLARED_STOCK_FAILED_REQUEST callback; if you do not register it, no notification is sent.

Request

The system will make one request with a short timeout. The response is not acted upon.

Callback fields:

request fields:

response fields:

error fields:

reason values:

Example:

{
  "type": "DECLARED_STOCK_PROVISION",
  "request": {
    "url": "https://your-domain.example/declared-stock/provision",
    "body": "{\"action\":\"PROVIDE\",\"orderId\":\"6ce660cc-4abe-11ed-b878-0242ac120002\",\"originalOrderId\":null}"
  },
  "response": {
    "status": "200",
    "body": "{\"action\":\"PROVIDE\",\"orderId\":\"6ce660cc-4abe-11ed-b878-0242ac120002\",\"success\":false}"
  },
  "error": {
    "reason": "provision_not_successful",
    "details": "ProvisionRequest completed, but the \"success\" flag is false"
  }
}

Response

No response body is expected. A successful (HTTP status 200) response acknowledges receipt. Eneba does not retry this notification regardless of your response.

2. Activating the "Declared Stock"

To prevent unwanted reputation damage on production environment, we require you to integrate your implementation of "Declared Stock" with our Sandbox Environment.

We have a dedicated guide to help you to test your "Declared Stock" integration on the Sandbox.

When your integration is ready on the Sandbox, you are now able to activate the feature by calling P_enableDeclaredStock mutation.

3. Tracking your "Declared Stock" errors

You will find the declared stock dashboard useful for debugging errors and setting up your integration.

You can also get the errors we have found while calling your "Declared Stock" integration with the P_declaredStockResult query.

4. Disabling "Declared Stock" feature

In order to disable "Declared Stock" feature, you have to update your auction with declaredStock: null Not providing declaredStock field will not disable "Declared Stock" feature, neither setting it to zero.

When the declaredStock value becomes zero, Eneba still will have auction enabled and will issue a Reservation callback. This is done due to possible delays between stock coming down to zero, and you still have not updated the auction with a fresh declaredStock value.

Please find more on S_updateAuction mutation.

5. Update the "Declared Stock" value often

To keep your stock information up-to-date, we recommend updating the auction's declaredStock value often.

6. Key returns

You should expect that the purchased keys can be returned. The returned keys will be stored in the Eneba stock. You can leave them there or could remove them by calling the S_updateAuction mutation.

7. Additional sequence diagrams

Canceled sale

The following example illustrates the canceled sale when User declines the payment or Eneba cancels the order.

Unfulfilled sale

The following example illustrates two scenarios when Merchant is unable to fulfil the callbacks.

• Merchant failed to fulfil the Reservation, which may result in disabled auction.
• Merchant failed to fulfil the Provision, which result in commissions being charged and auction may be disabled.