Stock queries

Guidelines

Creation of a new query

To create a new query, click on the button “Add a stock location query”.

You'll need to give it a name, and then choose whether the query should inherit from another existing query or not.

If you choose to inherit from an existing query, you won't be asked for any additional parameters, as you'll get back all those set on the parent query.

However, if you choose to create a query without inheritance, you will be prompted for export and unification parameters. These parameters can be modified after creation, and a more detailed explanation is given in the following documentation.

Aggregates

A stock query is a sum of aggregates representing a scope of stock locations on particular items, for which some elements are deducted. Then, settings adjust the response according to specific needs. Here is a diagram of a stock request.

Each aggregate represents a scope of stock locations on a scope of items. All aggregates are added together, so no stock location must be returned in two different aggregates, otherwise the stock response will be doubled.

When creating an aggregate, you need to define a name and then specify which stock locations and item queries will be used to represent the aggregate.

Stock locations and items queries

Once selected at the creation, queries are visible by unfolding the aggregate. The "Edit" button is used to modify the query and also to change the parameter “force usage of the filter requested” (details below). There's also a redirect button that opens another window on the item or stock location query.

Force usage of stock location/item filter requested.

When selecting stock locations and items queries, you must choose whether or not to activate it. It is important to understand this parameter, as it can have an impact on the results of the stock query.

When users uses the API GET /stock_export route, they won't necessarily want to retrieve all possible values, but only on particular items or stock locations. They can therefore use filters as shown below.

GET /stock_export
{
    "site_id": "cxxx",
    "request_name": "newquery",
    "aggregates": {
        "*": {
            "item_filter": {
                "ids": [
                    "ITEM_001"
                ]
            },
            "endpoint_filter": {
                "ids": [
                    "STORE_001"
                ]
            }
        }
    }
}

If the Force usage of stock location/item filter requested parameter is enabled, filters will be taken into account. Otherwise, they will be ignored and all results will be returned.

Stock type filter

In most cases, there is only one type of stock set up in Onestock that represents available stock, so this filter can be ignored. But if the project uses several types of inventory (to manage future stocks, for example) this parameter can be useful, as it will only return the stock types you're interested in.

You can even filter on periods of future stock availability, as shown below.

Deductions

Deductions are elements that will be decremented from the stock results of the aggregate. We recommend that you activate the following 4 deductions:

• Types of unavailability: There are different types of unavailability declared in store, depending on the reason given by the vendor. You must indicate the types you wish to deduct from the available stock. We advise you to select the not_in_stock type.

• Stock locations reservations: You need to Indicate the sales channels on which store reservations are to be taken into account.

• Global buffers: You need to indicate the global buffers to be deducted. If several buffers are selected, the one with the highest value will be applied.

• Stock locations buffers: You need to indicate the stock locations buffers to be deducted. If several buffers are selected, the one with the highest value will be applied.

Settings

Once the sum of the stock aggregates has been achieved, we can adjust 4 different parameters to obtain an appropriate stock response.

Global reservations

This parameter is used to deduct global item reservations from the sum of aggregates. Global reservations are generally created in Onestock when the order is created, and disappear when the items are claimed, to be transformed into stock locations reservations.

In particular cases, you can choose to take into account global reservations only on a list of sales channels, but in general you should leave the "All sales channels" parameter checked.

Unification

The unification adds up all stock lines and returns a single global value. This setting is very important as it will completely change the format of the stock response.

The most common form of unification is by stock locations, but you can also unify by stock type if you have more than one configured on your project.

If the query is unified by stock locations, then the "unified" badge will be visible in the main page tree. Otherwise, the badge will be "detailed".

Stock export

This setting allows to configure the “export” queries used to update stock availability on the website.

• Diff/Full: If the "Full" parameter is checked, all stocks returned by the query will be sent. If "Diff" is checked, exported stocks are those that have changed since the last export on the same scope. As the full export is very large, it is usually set to be sent once in the morning. Then, several diff exports are sent at regular intervals during the day.

• Scope key: This key, mandatory to perform diff exports, is a freely definable id which identifies a stock perimeter on which the export will be done. This can be a sales channel, a country, etc... When a diff stock is exported, only movements that have taken place since the last export on the same key are counted. Once exported, the counters are reset to 0 for this key, but not for the others.

• Export 0 for unreferenced items: If this parameter is enabled, when a stock line is unreferenced, a quantity of 0 will be returned in the export following the unreferencing. An unreferenced stock line is one that no longer exists in the database, or for which's stock location or item is no longer included in the item or stock location queries. This feature requires a specific configuration at the site level to work, contact your OneStock point of contact for assistance.

• Export stock difference instead of raw value: If enabled, the values returned will represent the stock difference from the last export. This difference can be positive or negative. If deactivated, raw stock values will be exported.

Details

This final setting allows you to return more detailed results.

• Return details of deductions: deducted elements such as buffers, unavailabilities or reservations are returned.

• Return custom information: custom information sent during the stock import is returned.

Onestock advices

Basic queries

We advise you to create the basic queries, i.e. :

• detailed - this basic query is supposed to return all available stocks from all stock locations on all items. A single aggregate all can be created, which can refer to endpoints and items queries, and with all deductions set. Only the setting of global reservations can be added.

  • unified - the query inherits from detailed. Only the setting of unification (by stock type and by stock location) has to be enabled.

For orchestration

We recommend that you separate orchestration requests according to delivery type. In our example, we have 3 types of delivery: Ship From Store, Click & Collect standard and Click and Collect express.

For better consistency, we recommend you adopt the following naming convention : orchestration_{detailed/unified}_{delivery type}_{country/sales channel)

• Ship From Store:

  • orchestration_detailed_sfs - This query can be created at the root to target the stocks available for SFS orchestration. It can be used in rulesets that do not make differences between countries or sales channels. It should contain two aggregates "stores" and "warehouses" which are the two order fulfillment paths.
    - The “stores” aggregate should contain the items_sfs items query, which lists items eligible for order-taking, and the stores_sfs stock locations query, which lists stores with the Ship From Store module enabled. The parameter “Force usage of stock location filter requested” must be disabled for the stock locations query.
    - The “warehouses” aggregate should also use the items_sfs items query, and the warehouses_sfs stock locations query, which lists warehouses with the Ship From Store module enabled. The parameter “Force usage of stock location filter requested” must be disabled for the stock locations query.
    All aggregate deductions can be activated (buffers, reservations and unavailabilities) as well as the global reservations parameter.

    • Then, the unified query orchestration_unified_sfs can be created by inheriting from the detailed one. Only the “Unification” parameter should be changed (unification by sock locations and stock types enabled).

  • orchestration_detailed_sfs_{country} - This query can be created by inheriting from the previous one to target a particular country or sales channel. If we consider that the warehouse can deliver to any country, then the "warehouses" aggregate can remain unchanged. However, we need to modify the "stores" aggregate so that it uses the stores_sfs_{country} stock locations query to target only stores in the chosen country.

    • Then, the unified query orchestration_unified_sfs_{country} can be created by inheriting from the detailed one. Only the “Unification” parameter should be changed (unification by sock locations and stock types enabled).

➡️ Here's what the Ship From Store orchestration queries might look like, differentiating between the two countries "FR" and "UK".

• Click and Collect express:

  • orchestration_detailed_ckc_exp - This query can be created at the root to target only the pick-up store. As there will be no shipping, it should contain only one aggregate “destination_store” regardless of the country or the sales channel.
    - The “destination_store” aggregate should use the items_ckc items query, and the stores_cfs stock locations query which lists stores enabled in Collect From Store (in-store pick-up). Since we want to target ONLY the destination store, we'll need to enable the parameter “Force usage of stock location filter requested” for the stock locations query.
    All aggregate deductions can be activated (buffers, reservations and unavailabilities) as well as the global reservations parameter.

    • Then, the unified query orchestration_unified_ckc_exp can be created by inheriting from the detailed one. Only the “Unification” parameter should be changed (unification by sock locations and stock types enabled).

➡️ The result is a single pair of stock queries for Click & Collect express, regardless of country or sales channel.

• Click and Collect standard:

  • orchestration_detailed_ckc_std - This query can be created at the root to target the stocks available for standard Click & Collect orders, whether the stock is directly available in the pick up store or sent from another stock location. It can be used in rulesets that do not make differences between countries or sales channels. It should contain 3 aggregates "stores", "warehouses" and “destination_store” which are the three order fulfillment paths.
    - The “stores” aggregate should contain the items_ckc items query, which lists items eligible for Click & Collect, and the stores_sfs stock locations query, which lists stores with the Ship From Store module enabled who will be able to ship the order to the pick-up store. The parameter “Force usage of stock location filter requested” must be disabled for the stock locations query.
    - The “warehouses” aggregate should also use the items_ckc items query, and the warehouses_sfs stock locations query, which lists warehouses with the Ship From Store module enabled who will be able to ship the order to the pick-up store. The parameter “Force usage of stock location filter requested” must be disabled for the stock locations query.
    - The “destination_store” aggregate should also use the items_ckc items query, and the stores_cfs_not_sfs stock locations query which lists stores enabled in Collect From Store (in-store pick-up) but not enabled in Ship From Store otherwise they will be double-counted with the "stores" aggregate. Since we want to target ONLY the destination store, we'll need to enable the parameter “Force usage of stock location filter requested” for the stock locations query.
    All aggregate deductions can be activated (buffers, reservations and unavailabilities) as well as the global reservations parameter.

    • Then, the unified query orchestration_unified_ckc_std can be created by inheriting from the detailed one. Only the “Unification” parameter should be changed (unification by sock locations and stock types enabled).

  • orchestration_detailed_ckc_std_{country} - This query can be created by inheriting from the previous one to target a particular country or sales channel. If we consider that the warehouse can deliver to any country, then the "warehouses" and “destination_store” aggregates can remain unchanged. However, we need to modify the "stores" aggregate so that it uses the stores_sfs_{country} stock locations query to target only stores in the chosen country.

    • Then, the unified query orchestration_unified_ckc_std_{country} can be created by inheriting from the detailed one. Only the “Unification” parameter should be changed (unification by sock locations and stock types enabled).

➡️ Here's what the standard Click & Collect queries might look like, differentiating between the two countries "FR" and "UK".

For stock export

Stock exports requested from Onestock by websites allow product availability to be updated.

In general, stock exports are separated by sales channels and/or different websites. For example, if both UK and FR websites exist in your project, you will need to configure independent stock export flows between UK and FR.

For each sales channel, you will need to set up unified/detailed and full/diff queries. In general, the “full unified” query is called once a day in the morning to initialize product availability on the website. Then, the “diff unified” are called up regularly throughout the day to adjust stock levels according to sales. Full and diff detailed queries should generally not be called up without using a filter, as the data is too voluminous.

• export_detailed_{saleschannel}_full - This query can be created at the root to target the details of all stocks available for delivery. As the Ship From Store orchestration query, it should contain two aggregates "stores" and "warehouses" which are the two scopes of stock availability.
  - The “stores” aggregate should contain the items_sfs items query, which lists items eligible for order-taking, and the stores_sfs_{saleschannel}_export stock locations query, which lists stores eligible for export with the Ship From Store module enabled. The parameter “Force usage of stock location filter requested” can be enabled for the stock locations query, this will allow you to filter on specific stock locations if necessary.
  - The “warehouses” aggregate should also use the items_sfs items query, and the warehouses_sfs_{saleschannel}_export stock locations query, which lists warehouses eligible for export with the Ship From Store module enabled. The parameter “Force usage of stock location filter requested” can be enabled for the stock locations query, this will allow you to filter on specific stock locations if necessary.
  All aggregate deductions can be activated (buffers, reservations and unavailabilities) as well as the global reservations parameter.
  Next, the export parameter should be enabled with the “Full” option. A scope key must be specified to identify the perimeter of the export and must be identical to the diff export. It could be, for example “detailed_fr”.

  • Then, the unified query export_unified_{saleschannel}_full can be created by inheriting from the detailed one. The unification parameter should be changed (unification by sock locations and stock types enabled), and also the scope key of the export parameter. It could be, for example “unified_fr”.

• export_detailed_{saleschannel}_diff - This query can be created by inheriting from the “Full” one. Aggregates must remain unchanged.
  However, the export parameter must be changed to "Diff". Make sure the scope key remains the same as the full query, in my example “detailed_fr”. Then, the "Export stock difference instead of raw value" parameter can be activated or deactivated as needed for your project.

  • Then, the unified query export_unified_{saleschannel}_diff can be created by inheriting from the detailed one. The unification parameter should be changed (unification by sock locations and stock types enabled), and also the scope key of the export parameter. It could be, for example “unified_fr”.

➡️ Here's what the export queries might look like, differentiating between the two sales channels/websites "FR" and "UK".

For add-on modules

Stocks queries are also used on add-on modules such as the OIS catalog, the e-reservation funnel or the delivery promise and so need to be set up.

• Order in Store catalog: These queries provide the availability of products in the Store App catalog. The “immediate pickup” availability is based on the detailed query, and the “ordering” availability is based on the unified query

  • ois_detailed - This query is only used to provide the “immediate pickup” availability, and so can be created at the root to target the current OIS store. It should only contain one aggregate "pickup_store"
    - The “pickup_store” aggregate should use the items_ois items query, and the stores_ois stock locations query which lists stores enabled in Immediate Pickup. Since we want to target ONLY the current store, we'll need to enable the parameter “Force usage of stock location filter requested” for the stock locations query because the store app will add the filter to the query.

  • ois_unified_{saleschannel} - Then, the unified query is used to provide the “ordering” availability on a given sales channel. This query should looks like the export_unified_{saleschannel}_full one, because we will set up the same aggregates (“stores” and “warehouses” enabled for export). The parameter “Force usage of items filter requested” must be enabled for both aggregates.
    However, the export parameter must not be enabled (if a scope key is set, this may affect diff exports).
    The unification parameter must be enabled (unification by stock types and stock locations).

➡️ Here's what the OIS queries might look like, with a single detailed query at the root, and two unified queries for the two sales channels/websites FR and UK. The UK inherits from the FR, and only the “stores” aggregate is changed.

• E-reservation: These queries provide the availability of products in the Onestock’s e-reservation funnel in the website. The unified query is used to display or not the product as available for e-reservation, and the detailed one displays the list of available stores.

  • eresa_detailed - This query is used to target all available stores, so it should only contain one aggregate "stores".
    - The “stores” aggregate should contain the items_eresa items query, which lists items eligible for Reserve & Collect, and the stores_eresa stock locations query, which lists stores with the e-reservation module enabled.

• Delivery promise: