Automate Your Stock with "Declare Stock"

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

During the purchase process, Driffle.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. Note: Declare stock is enable for pre-order product, please check pre-order offer creation for more details.

Example

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

Important

  • It is required that your "Declared Stock" implementation is configured & tested.

  • If the Provision request will end up in a failure, you will be charged the commission amount under the Unfulfilled Sale Fee.

  • Driffle will put cooldowns on your offer i.e hide your offers, if the ratio of failed and completed requests in last hour is higher than the below thresholds:

    • Reservation Requests:

      • 40% failures threshold is reached.

      • Driffle may hide your offer for 2 hours.

      • Driffle may extend the cooldown period on consecutive failures. After 2 or more consecutive cooldowns, the following cooldown shall be extended to 24 hours.

    • Provision Requests:

      • 20% failures threshold is reached.

      • 3 consecutive failures in provision.

      • Driffle may hide your offer for 2 hours.

      • Driffle may extend the cooldown period on consecutive failures. After 2 or more consecutive cooldowns, the following cooldown shall be extended to 24 hours.

  • Driffle Uses only HTTPS scheme for callbacks.

Enabling "Declared Stock" Feature

You can enable the declared stock feature directly from your driffle's dashboard. Follow the below steps to enable declared stocks for you:

  1. Login to your seller dashboard

  2. Go to Seller settings > Declared Stock

Seller Menu

  1. Declared Stock Configuration

    • Step - 1: Add Your Domain & verify the ownership:

    Domain ownership can be proven in two ways:

    1. DNS TXT record validation

    2. Hosted file validation

    Constraints for the domain name field

    • Must be the base domain of your service. e.g. - callback.driffle.com

    • Must not be IP address

    • Domain length must not be greater than 500 characters

    • Must not contain query strings

    Valid Domains -

    www.yourdomain.com yourdomain.com api.yourdomain.com

    Invalid Domains - http://www.yourdomain.com - ("http://" present) https://www.yourdomain.com - ("https://" present) https://0.0.0.0 - (is IP address and "https://" present) www.yourdomain.com?action=reservation - (contains query strings)

    DNS TXT record validation

    DNS TXT record validation is the preferred validation mechanism as it is faster and does not make requests to your system meaning less load for your servers.

    • Copy the TXT record value from the Driffle dashboard above

    • Add this value into your DNS provider configuration as TXT record

    • Hit the "Verify" button on your dashboard

    • Driffle will verify the TXT record value in the base domain you entered in step 1. e.g. - driffle.com

    Hosted file validation

    Driffle will attempt to get the driffle-verification.txt file from your domain before making any API callback request.

    • Download the file from the Driffle dashboard above

    • Upload it directly to your domain. It must be available at https://yourdomain.com/driffle-verification.txt

    • Hit the "Verify" button on your dashboard

    If validation is successful, you now may register your APIs in the next steps.

    • Step - 2: Setup Dummy Product Offer (For Testing)

    Since, we had deprecated our sandbox environment, We will be setting up a Dummy Product (ID: 34547) to test declared stock endpoints by creating an offer for it on Driffle with minimum 5 keys. This is to test all the callbacks on Production environment.

    Dummy product is private to you and can only be accessed through APIs. No other users on Driffle can see this.

    This is to test all the callbacks on Production environment.

    1. There are three endpoints to be tested and verified to getting started with Declared Stock Feature.

    2. You will be providing Reservation, Cancellation and Provision endpoints in the next steps for verification.

    3. It is required to keep minimum 5 dummy keys in your key pool for a smooth verification process.

    URL Verification Process - Reservation -> Cancellation -> Reservation -> Provision

    Dummy product setup

    • Step - 3: Register Callbacks

    Enter the mandatory Reservation, Cancellation, Provision API paths in the fields on Driffle Dashboard.

    Callback endpoints

    Callback Path Validations -

    1. Path must not start with a "/" (It is added by us after service URL as displayed in screenshot above)

    2. Path must not end with a "/"

    3. Path must not contain any query strings `?`

    URL Verification process will be as follows -

    1. All the below endpoint requests will require a mandatory API key to be sent as the Authorization header as Bearer Token for your systems to identify the validity of each request. e.g. - Bearer <YOUR_API_KEY>

    2. Reservation Endpoint will be called by our systems to Seller domain systems on dummy product offer.

    3. On Successful verification of Reservation Endpoint, Cancellation Endpoint will be called by our systems on dummy product offer.

    4. On Successful verification of Cancellation Endpoint, Reservation Endpoint will again be called on dummy product offer.

    5. On Successful verification of Reservation Endpoint for the second time, Finally, the Provision Endpoint will be called against the same Reservation

    6. On successful verification of all URLs, the second step to complete Declared Stock Feature Integration will be completed.

    • Step-4: Review Terms & conditions and Enable Declared Stock Feature

    Click on "I agree" to agree with Driffle's Terms And Conditions for Declared Stock to complete the declared stock feature integration.

After successful verification, you will be eligible to use Update Declare Stock API for all other offers on Driffle.

1. Sequence diagrams

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

Successful Sale Flow

Successful Sale

Canceled sale Flow

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

Cancelled state sequence diagram

Unfulfilled Sale Flow

The following example illustrates two scenarios when Seller is unable to fulfill the callbacks.

  • Seller failed to fulfill the Reservation, which may result in disabled auction.

  • Seller failed to fulfill the Provision, which result in commissions being charged and auction may be disabled.

Unfulfilled Sale Sequence Diagram

2. Reservation

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

We recommend holding the reservations for up to 12 hours - this is the longest payment await duration in Driffle.

Request Body 

```json
{
    "orderId": "aArg23fvas",
    "offers": [
        {
            "offerId": 23452,
            "quantity": 1,
            "price": {
                "sellingPrice": 5,
                "youGetPrice": 4,
                "currency": "EUR"
            }
        }
    ]
}
```

Request Body Fields -

Field
Type
Description

orderId

string

Reservation Order Id for purchase

Offers

[ReservationOffer]

Array of offers for purchase in order

ReservationOffer Field -

Field
Type
Description

offerId

number

Driffle OfferId

quantity

number

The number of keys to purchase for a given offer

price

object

An object sellingPrice, youGetPrice and currency with the prices for a single key

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.

This is the expected response schema from Seller Systems for a Reservation to be considered successful.

```json
{
    "message": "",
    "data": {
        "orderId": "aArg23fvas",
        "offers": [
            {
                "offerId": 23452,
                "success": true
            }
        ]
    }
}
```

3. Cancellation

The system will make one request to the Cancellation endpoint with below payload in case of payment failures from User end or Driffle Cancels the Order.

Request Body 

```json
{
    "orderId": "aArg23fvas"
}
```

Response

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

4. Provision

The system will make three attempts with a 5s sleep interval and 60s 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 (60 seconds)

  • Wait time: 5 seconds

  • Request 3: Fails

  • Order gets cancelled

Please note: On approval basis this can be extended to 10 Requests.

Request Body 

```json
{
    "orderId": "aArg23fvas"
}
```

Response

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

```json
{
    "message": "",
    "data": {
        "orderId": "aArg23fvas",
        "offers": [
            {
                "offerId": 23452,
                "keys": [
                    {
                        "type": "TEXT",
                        "value": "0o4nhb"
                    }
                ]
            }
        ]
    }
}
```

Response Data Fields -

Field
Type
Description

orderId

string

Reservation Order Id for purchase

offers

[ProvisionOffer]

Array of offers with keys in order

ProvisionOffer Fields -

Field
Type
Description

offerId

number

Driffle OfferId

keys

[Key]

A collection of keys, see below

Key Fields -

Field
Type
Description

type

Enum

Either TEXT or IMAGE. Indicates the key format

value

string

A plain-text or base64-encoded image

Important Note -

  • Image type keys provided in Provision response must be of the following types only: jpg, jpeg,png.

  • Only raw base64 is supported. Please remove any HTML/CSS attributes, like data:image/png;base64,

// Need a code snippet to convert an image file into base 64 string

5. Disabling "Declared Stock" feature

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

When the declaredStock value becomes zero, Driffle 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.

6. Update the "Declared Stock" value often

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

7. Key returns

You should expect that the purchased keys can be returned. The returned keys will be stored in the Driffle stock. You can leave them there or could remove them by Driffle Dashboard.

PreviousCannot use the API, it throws 401/403/404 errorsNextAutomate Pricing

Last updated