> For the complete documentation index, see [llms.txt](https://docs.driffle.com/driffle-seller-api-legacy/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.driffle.com/driffle-seller-api-legacy/reference/automate-your-stock-with-declare-stock.md). # 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`](#reservation) request. The second one will ask you to provide the purchased keys, called a [`Provision`](#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](https://driffle.com/user/selling/dashboard) to your seller dashboard 2. Go to Seller settings > Declared Stock

3. **Declared Stock Configuration** * **Step - 1: Add Your Domain & verify the ownership:** Domain ownership can be proven in two ways: 1. [DNS TXT record validation](#dns-txt-record-validation) 2. [Hosted file validation](#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](http://www.yourdomain.com) \ yourdomain.com \ api.yourdomain.com > > **Invalid Domains -** \ - ("http\://" present)\ - ("https\://" present)\ - (is IP address and "https\://" present)\ [www.yourdomain.com?action=reservation](http://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`

* **Step - 3: Register Callbacks** Enter the mandatory `Reservation`, `Cancellation`, `Provision` API paths in the fields on Driffle Dashboard.

**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 ` 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](/driffle-seller-api-legacy/reference/api-reference/manage-inventory-stock/declare-stock.md#offer-declare-stock-id) 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**

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

**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.

### **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 ```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 ```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 ```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 ```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 ```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](/driffle-seller-api-legacy/reference/api-reference/manage-inventory-stock/declare-stock.md#offer-declare-stock-id). 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](/driffle-seller-api-legacy/reference/api-reference/manage-inventory-stock/declare-stock.md#offer-declare-stock-id). ### 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. ## Offer Cooldown & Automated Reactivation ### Summary If your reservation or fulfillment requests fail too often, Driffle will temporarily pause the offer automatically. During this time: * Customers cannot see or buy the offer * Sellers cannot edit the offer status * Driffle automatically checks later if the offer is working again After the cooldown period ends, Driffle sends a test reservation request to your reservation webhook. * If the test succeeds → the offer becomes active again * If the test fails → the offer stays in cooldown and another check happens later These test requests use the same webhook as normal orders, but they are not real purchases. *** ### When cooldown is triggered Cooldown applies only to active offers\ Reservation failures Triggered when declared-stock reservation calls fail repeatedly: | Window | Condition | | ---------- | ---------------------------------------------------- | | 1 hour | More than 5 failures and failure/success ratio ≥ 40% | | 15 minutes | More than 3 failures | #### Fulfillment (allocation) failures | Window | Condition | | ----------- | ---------------------------------------------------- | | 1 hour | More than 5 failures and failure/success ratio ≥ 20% | | 15 minutes | More than 2 failures | | Consecutive | More than 2 consecutive failures | *** ### Cooldown duration | Occurrence | Duration before reactivation check | | ----------------------------- | ---------------------------------- | | First cooldown | 2 hours | | Second or later (consecutive) | 24 hours | You receive an email and an in-dashboard notification when cooldown starts. *** ### Automated reactivation (release) flow

#### What the health check does 1. Sends one reservation request to your configured reservation URL. 2. If your API returns success, immediately sends a cancellation request for the same orderId. 3. Restores the offer to its pre-cooldown status (usually active). No customer order is created. No keys should be allocated or charged. **Monitor API Logs in Seller Dashboard:** * Log: Declared Stock * View: Cooldown *** ### FAQ #### Why do I receive reservation webhooks for offers I cannot edit? Your offer is in cooldown. Driffle blocks seller edits while the system manages reactivation. The webhooks are automated health checks, not customer purchases. #### Are cooldown offers visible on the marketplace? No. Only offers with status active and available stock are purchasable. Cooldown offers are hidden from customers. #### I see "Forbidden by admin" when updating an offer The offer is disabled. Offer status can be changed via the seller API until the restriction is lifted.\ Why can't I update the offer during disabled? During disabled, Driffle temporarily controls the offer status while automatic recovery checks are running. You can still update: * Stock * Price * Declared stock quantity However, you cannot: * Reactivate the offer manually * Change the offer status while cooldown is active