# Norce Commerce Availability structures

Norce Commerce offers a flexible and dynamic method for displaying availability information on applications. You can set up automatic integration of on-hand
product information across the different warehouses, and use Norce's business rules and configurations to determine which data to present to applications for
the most accurate availability promise possible.

## Availability shown on a product

A product or variant in Norce Commerce Services will give three different on-hand information elements:

![On hand model](/assets/availability-structure-1.7895ad6a0a10de41354c48917c2fb63f2266be3103c618a8033e7719e0a85529.03197a83.png)

- **OnHand**
This information is based on an aggregation of all warehouses (and their locations) configured for the specific application and price list used.
- **OnHandStore**
This information based on an aggregation of all stores that are added to the storeSeed parameter and have store warehouses. You can find storeId's by calling
`ListStores2` in the application service.
- **OnHandSupplier**
This is availability information from the primary supplier chosen based on rules in Norce for the specific price list used.


### Important fields

- **`Value`'**: The number of units currently available in the warehouse, except for those already reserved by Norce (if reservations are enabled for the
client)
- **`IncomingValue`** and **`NextDeliveryDate`**: If more items are ordered from the supply chain, the incoming value shows how many are on the way, and the
next delivery date is the estimated time of arrival in the warehouse for the earliest batch.
- **`LeadTimeDayCount`**: The number of days (or other time unit specified in the setup) it approximately takes to ship items to the customer.
- **`IsReturnable`**: A flag that can be set from the source of the on-hand information, for example the supplier can inform that this particular item is
non-returnable (to them).
- **`Info`**: This field is empty when returned with product data but is used to provide extended information when returned for specific warehouse information (
see below).


#### Other fields on Product (and Variant)

- **`StockDisplayBreakPoint`**: This value can be set in Norce (Stock Breakpoint) either on the category or on the product (variant). It is a marker that can
signal certain behavior in the availability logic. For example, if a product has 5 units left, and the `StockDisplayBreakPoint` is set to 10, instead of
showing the number of units left in the app, a text such as "only a few left" should be displayed.
- **`IsDropShipOnly`**: This flag can be set in Norce Commerce (Dropshipping only) either on the category or on the product (variant). When enabled, Norce handles
the product differently in the business rules, and the availability logic should signal that the supplier on-hand information should be used instead of the
local on-hand (even if the value is greater than 0).


### About interpreting availability data

There's almost always a client-specific logic to set up in the presentation layer. As described above, Norce Commerce returns the On Hand values and other
information that can be used for setting up different availability display options.

Note
Exactly how to present availability from the data in Norce Commerce is entirely up to the client implementation. The examples below are simply suggestions.

The important fields mentioned above (excluding on-hand value) can be used more freely to represent whatever is desired. For instance, `LeadTimeDayCount`,
`IncomingValue`, and `NextDeliveryDate` can be utilized to more specifically convey the intended message to the presentation layer. In this way, a source system
can communicate a more direct message to the presentation layer. While Info types can also help with this, they will only be displayed on on-hand checks and not
on the aggregated values. For more information about how to extend the availability data, refer to the documentation on extending availability.

Read about how to extend the availability data [here](/solution-portal/detailed-design/extend-availability).

#### Example 1 - B2C use case

Suppose a B2C app that doesn't want to show the exact number of units but wants to give a fair availability promise to the end-customer. The following table
provides an example of how to decide what to display in the frontend:

| Description | Criteria | Lead time | Display |
|  --- | --- | --- | --- |
| Plenty in local stock and a short lead time | On Hand value > Stock Breakpoint | Lead time = 1 | “deliver in 1-3 days” |
| Plenty in local stock and a longer lead time | On Hand value > Stock Breakpoint | Lead time > 1 | “deliver in 4-10 days” |
| Short supply in local stock | On Hand value <= Stock Breakpoint | - | “only few left, 1-3 days” or show “only few left, 4-10 days” |
| Nothing in local stock, but units incoming | On Hand value <= 0, Incoming > 0, NextDeliveryDate exists | Lead time exists | “estimated delivery [nextdeliverydate + lead time]” |
| Nothing in local stock, no units incoming, but stock at supplier | On Hand value <=0, Incoming = 0, Supplier On Hand > 0 | Lead time (supplier) = X | “estimated delivery [X]-[X+5] days” |
| Dropshipping only product, with stock at suppler | DropShipping Only = true, On Hand value = any, Incoming = any, Supplier On Hand > 0 | Lead time (supplier) = X | “estimated delivery [X]-[X+5] days” |
| Dropshipping only product, with no stock at suppler | DropShipping Only = true, On Hand value = any, Incoming = any, Supplier On Hand = 0 | - | “estimated delivery over 3 weeks” |


#### Example 2 - B2B use case

A B2B app that would show more detailed information to the end-customer:

| Description | Criteria | Lead time | Display |
|  --- | --- | --- | --- |
| local stock and a lead time | On Hand value = X | Lead time = 1, > 1 (Y) | “X in stock, deliver in 1 day”“X in stock, deliver in Y days” |
| Nothing in local stock, but units incoming | On Hand value <= 0, Incoming > 0, NextDeliveryDate exists | Lead time exists | “Not in stock, estimated delivery [nextdeliverydate + lead time]” |
| Nothing in local stock, no units incoming, but stock at supplier | On Hand value <=0, Incoming = 0, Supplier On Hand > 0 | Lead time (supplier) = Y | “X in stock, estimated delivery in [Y] days” |


### On Hand checks

There are other ways to obtain availability data without retrieving it together with the products.

- `GetProductOnHandByPartNo` and `GetProductOnHandByProductId`: These two methods require a list of specific warehouses to query on-hand for a specific product,
and return on-hand information on each warehouse in the list. No aggregation (like in Product calls) is done, and the call bypasses the Norce Commerce
Services cache.
- `ListProductOnHandByBasket`: This method is similar to the methods above, but instead of a `productId`, it takes a `basketId` and returns availability
information for all products in the basket.



```Json

[
  {
    "_Comment": "Example of how the warehouse input looks",
    "WarehouseId": 529,
    "LocationId": 529
  },
  {
    "StoreId": 268
  },
  {
    "StoreId": 269
  },
  {
    "WarehouseId": 4131,
    "LocationId": 4131
  }
]
```

Note
The extendable info types are only returned when calling these methods, since it is not possible to aggregate them.

`Warehouse` and `StoreId` can be found by calling `Listwarehouseinfo`.

### Reservations

Norce Commerce provides a reservation functionality that can be enabled for clients. When an order is created, reservations are added to the product for the
standard warehouse on the used price list. The next time Norce returns availability, the on-hand value will be reduced by the reservation value. This way, you
can handle availability promises for sensitive products. The reservation is cleared when a new on-hand update is passed in to Norce on the
warehouse. 

#### **Example:**

1. A product purchased on the Standard pricelist.
The warehouse set as “Standard” for the price list used gets reservations.


![Connected warehouses](/assets/availability-structure-2.83eb244aac43f8008c5f636b3c6f64e52dd60327f8ab792a58a35549b500cf43.03197a83.png)

1. These reservations are shown in the admin.
This client has reservation enabled and in this case, 3 pcs are reserved for a product:


![On hand info](/assets/availability-structure-3.8b18954908e946f55b24d0e49ac927f09602598dcd7ae78a87c1dc5fcc1faee3.03197a83.png)

> Note that **515** is not the stored `OnHand` value, it is actually **518**.


1. When getting `OnHand` for the specific warehouse from Norce we get:


![On hand result](/assets/availability-structure-4.b432ab05b114bd50039265d4b89e0f8a07ac770738d6d8c8b2d5bc8a54843c21.03197a83.png)

1. Later, a new `OnHand` value is passed in through connect:


![On hand import](/assets/availability-structure-5.995b71fb21e55dc5bfda042124b88a4b9cf8e322012a3d436d5625386f76fc64.03197a83.png)

The reservation is then set to **0** and `Onhand` is set to the new value **510**.

> To enable Reservation functionality set up `UseOnHandSubstraction` in client settings.


![Reservation client setting](/assets/availability-structure-6.524180f2f68b1d246ba104873ba3a24c4890965ac4ad8b5b832feedf4254e4b0.03197a83.png)

## How to configure availability in Admin

### Set up warehouses and locations

![warehouse configuration ](/assets/availability-structure-7.d3f1493fd4f313bbc28b1bfeebe50333a40c954d55eb1645d1a7f42ebddef25e.03197a83.png)

When setting up availability in Admin, it's important to create warehouses for all places of unit storage, and add a location as well. Here's what you need to
consider:

- **Code**: This identifier is used by integrations and imports, and should mirror the identifiers in source systems.
- **Type**: This refers to the type of warehouse, which could be:
  - *Warehouse*: The common warehouse for online distribution
  - *Store*: Specific for physical stores
  - *Transport*: An in-transit warehouse (very seldom used)
  - *Other*: Other types of warehouses that should not be shown in aggregated availability logic.
- **Primary**: This is the default warehouse for the client. Only one warehouse can be primary (optional).
- **Lead time**: This is the number of days (or any other time unit that is used in the setup) it approximately takes to ship items to the customer. This value
can be overridden on the product or variant.
- **Primary pricelist**: This points to the price list that is primarily associated with this warehouse. Usually, it's the main market price list.
- **Included in stock calculation**: This enables the warehouse to be part of the aggregation of stocks when Norce returns availability data.


#### **Which type of warehouse to choose?**

There are two scenarios in which the warehouse type are used by Norce Commerce:

1. *Aggregated availability data*
*OnHand* and *OnHandStore* display aggregated information from two types of warehouses, *Warehouse* and *Store*. The other two types *Other* and
*Transport* are not aggregated and the only way to see information about them is by calling the *On hand check methods*.
2. *Status rules*
Some status rules use on-hand information to determine if the status of a product should change. These in-stock-based status rules are only using
warehouses of the type *Warehouse*. The other are ignored. Read more about this
here: [Product status rules, In-stock based rules](/solution-portal/detailed-design/product-status-rules#in-stock-based-rules)


### Configure availability for applications, price lists

To restrict Norce Commerce from aggregating all warehouse information for all applications, it is required to set up a connection between the price lists and
the warehouses.

For example, the European market price list includes the European central warehouse and the large European physical stores, while the Swedish market price list
includes both the Swedish central and the European warehouses (as it serves the whole of Europe) and the Swedish physical stores.

![price list configuration ](/assets/availability-structure-8.2adbeebe94e86c34849b33157563912268bd07e95bea53311291bf76d0724ad8.03197a83.png)

Only one warehouse can be marked as “standard”, which means that it will receive reservations from all orders on the price list.

Note
Remember to add the warehouses to all price lists used in an application; even campaign and customer price lists require it to be able to calculate on-hand.

### Supplier On Hand configuration

To display supplier availability data, there are a few configurations that need to be set up.

![supplier onhand configuration ](/assets/availability-structure-9.764169ddb5332e47392f821aafcc6eeb5d6278bbab5bcc68a5ebe937ffbd89fe.03197a83.png)

1. Make sure that the supplier is enabled as the chosen supplier.
2. Connect the supplier price list to the supplier warehouse.
3. Connect the supplier price list to the price list.


By configuring this, Norce Commerce will retrieve the on-hand information from the current best-price price list, locate the supplier warehouse that is
connected, and return its on-hand data as availability.

## Import or integrate On Hand data

Onhand data can be manually updated in the Admin UI, imported from Excel files, and integrated using Norce Commerce Connect.

In Connect, client on-hand data is imported using

- `ImportOnhands` (in the product service)


while supplier on-hand information is imported together with other supply catalog data using

- `ImportProducts` (in the supplier service)


## Suggested further reading

- Onhand integrations
in [Product and pricing integrations](/developer-portal/system-integration/products-and-pricing-integrations#availability-information-to-norce-commerce)
- [Supplier integrations](/developer-portal/system-integration/supplier-integrations)
- [Availability on bundle products](/solution-portal/detailed-design/availability-on-bundles)
- [Additional information on availability](/solution-portal/detailed-design/extend-availability)