Store specific stock numbers¶
Retailers with both online and physical store channels, so called omnichannel retailers, frequently have a large share of visitors who use the site to explore the product range and discover items to buy, but still prefer making the actual purchase in the store. To cater to that need, Elevate supports supplying store specific stock numbers for variants. This enables visitors to get an experience that is tailored towards their preferred physical stores.
Supply store and stock information¶
Store and stock information is defined on variants in the data feed. Supply the online stock information in the stock number element, stock_number, of the variant and the store and store specific stock information in the stores element, stores, within the variant. If a store is not supplied on a variant that variant will be considered out of stock for that store, which is the same behaviour as if stock_number would be set to 0. The only difference between setting a store's stock_number to 0 and omitting the store is that the omitted store will not be returned in the availability array on the variant as opposed to the store being returned with stock number 0. Thus unless stores should be displayed with stock 0 we recommend to omit the store instead of setting stock_number to 0 in order to save on the amount of data being sent back and forth.
Query parameters¶
There are two query parameters related to store specific stock numbers: stores & channels. The stores parameter should contain the keys of the stores that the user on the site has selected as a pipe separated string. The stores provided will be taken into account to compute the stock status of products and variants for the query. The availability array on variants returned will show the online stock number and the stock numbers for all the stores in the stores parameter unless on a Product Page where all stores are always returned. The channels parameter can normally be omitted but needs to be used if the online (default) store should be ignored. The valid values for channels are ONLINE, ONLINE|STORE and STORE. ONLINE means ignoring the stores parameter, ONLINE|STORE means use both the online store and the provided stores, STORE means use only the provided stores. If STORE is explicitly provided (e.g. STORE or ONLINE|STORE), then stores is required and cannot be empty. Omitting channels is identical to ONLINE|STORE except that an empty or omitted stores is allowed. See query parameters for a detailed example with a table.
Example¶
The following example shows a site with stock levels online and in two physical stores identified by the store keys 240 and 100. The site has three products that are chainsaws, and each product has one variant.
Data feed¶
The information in the data feed for those products are as follows:
Simplified example data feed
<?xml version="1.0" encoding="UTF-8" ?>
<data_import type="full">
<modify market="US" locale="en-US">
<product_groups>
<add_or_replace>
<product_group key="1001">
...
<products>
<product key="1001-100">
...
<variants>
<variant key="1001-100-1">
<stock_number>10</stock_number>
...
<stores>
<store key="240">
<stock_number>5</stock_number>
</store>
<store key="100">
<stock_number>0</stock_number>
</store>
</stores>
</variant>
</variants>
</product>
</products>
</product_group>
<product_group key="1002">
...
<products>
<product key="1002-100">
...
<variants>
<variant key="1002-100-1">
<stock_number>10</stock_number>
...
<stores>
<store key="240">
<stock_number>0</stock_number>
</store>
<store key="100">
<stock_number>0</stock_number>
</store>
</stores>
</variant>
</variants>
</product>
</products>
</product_group>
<product_group key="1003">
...
<products>
<product key="1003-100">
...
<variants>
<variant key="1003-100-1">
<stock_number>0</stock_number>
...
<stores>
<store key="100">
<stock_number>1</stock_number>
</store>
</stores>
</variant>
</variants>
</product>
</products>
</product_group>
</add_or_replace>
</product_groups>
</modify>
</data_import>
The products and their stock levels can be summarized as following:
| Product key | Online stock level | Store stock levels |
|---|---|---|
1001-100 | 10 | 240: 5, 100: 0 |
1002-100 | 10 | 240: 0, 100: 0 |
1003-100 | 0 | 100: 1 |
Query¶
A query with the search phrase chainsaw is made to the search-page endpoint. Included in the query are additional parameters to show stock levels online and from the physical store with the key 240.
#!/bin/bash
curl -X GET \
'https://{cluster-id}.api.esales.apptus.cloud/api/storefront/v3/queries/search-page?market=US&locale=en-US&customerKey=b65f78d4-23f0-4043-bd5e-fea24b5837d3&sessionKey=cc6772fd-65e2-4392-a1ee-24977c99fd2e&touchpoint=desktop&limit=60&skip=0&viewId=production&q=chainsaw&channels=ONLINE%7CSTORE&stores=240'
const api = esales({ clusterId: 'w00000000', market: 'US', locale: 'en-US', touchpoint: 'desktop' });
const results = await api.query.searchPage({
q: 'chainsaw',
channels: 'ONLINE|STORE',
stores:'240'
});
Result¶
All the three chainsaws are returned. If the Only in stock facet had been used, the result would only include two of the three products matching the search phrase chainsaw as the third product, 1003-100, has no stock level online or in the selected store. Note that the availability array of the 1003-100-1 variant does not include an entry for store 240 since its stock_number is omitted for that variant.
Simplified example result
{
"q": "chainsaw"
},
"primaryList": {
"productGroups": [
{
"products": [
{
"key": "1001-100",
...
"inStock": true,
...
"variants": [
{
"key": "1001-100-1",
...
"inStock": true,
"stockNumber": 15,
...
"availability": [
{
"channel": "ONLINE",
"stockNumber": 10
},
{
"key": "240",
"channel": "STORE",
"stockNumber": 5
}
],
...
]
}
],
...
}
],
"key": "1001"
},
{
"products": [
{
"key": "1002-100",
...
"inStock": true,
...
"variants": [
{
"key": "1002-100-1",
...
"inStock": true,
"stockNumber": 10,
"availability": [
{
"channel": "ONLINE",
"stockNumber": 10
},
{
"key": "240",
"channel": "STORE",
"stockNumber": 0
}
],
...
}
],
...
}
],
"key": "1002"
},
{
"products": [
{
"key": "1003-100",
...
"inStock": false,
...
"variants": [
{
"key": "1003-100-1",
...
"inStock": false,
"stockNumber": 0,
...
"availability": [
{
"channel": "ONLINE",
"stockNumber": 0
}
],
...
}
],
...
}
],
"key": "1003"
}
],
"totalHits": 3,
...
}
The effects of the parameter combinations for this query is shown below:
| Channels | Stores | Displayed when filtering | 1001-100 result | 1002-100 result | 1003-100 result |
|---|---|---|---|---|---|
ONLINE|STORE | 240 | 1001-100, 1002-100 | inStock: truestockNumber: 15availability: online: 10, store 240: 5 | inStock: truestockNumber: 10availability: online: 10, store 240: 0 | inStock: falsestockNumber: 0availability: online: 0 |
For more information about the parameters, and how parameter combinations effects pages, see Stores and channels.