--- title: "Tutorial: Importing stock information" slug: "tutorial-importing-stock-information" updated: 2025-07-18T11:25:43Z published: 2025-07-18T11:25:43Z canonical: "docs.newstore.com/tutorial-importing-stock-information" --- > ## Documentation Index > Fetch the complete documentation index at: https://docs.newstore.com/llms.txt > Use this file to discover all available pages before exploring further. # Tutorial: Importing stock information After you follow the previous [product import tutorial](/v1/docs/tutorial-importing-products#tuto-import-product) , you now have product(s) available to sell in your business. In this tutorial, we add stock numbers to them to assign the quantity of items that you can sell. Stock information is at the core of the features offered by NewStore Omnichannel Cloud. > [!NOTE] > Important > > You import stock data that is allocated to a physical fulfillment location (distribution center or a store). This is different from products, which are allocated to a logical grouping called `shop`. > > > > Read [the integration guide](/v1/docs/importing-data#integ-importdata) to understand how the [Import API](https://docs.newstore.net/api/integration/catalog-sfcc/import-api_api) works. > > > > We assume that you have an authentication token stored in the `AUTH_TOKEN` variable. Retrieve one with the following call: > > ```bash > export AUTH_TOKEN=$(curl -s /v0/token -d \ > "grant_type=password&username=&password=" | jq -r .access_token) > ``` ## Pre-requisites > [!NOTE] > Important > > Before going through the import steps, ensure that a [store is created](/v1/docs/tutorial-setting-up-a-store) and [products are imported](/v1/docs/tutorial-importing-products). You may or may not have enabled NewStore as inventory master for your business. Follow the instructions for the use case that best describes your operational mode with NewStore. To understand how to manage distribution centers, see [Configuring distribution centers](/v1/docs/configuring-distribution-centers#config-dc). ## Import stock information for Distribution Centers (DCs) The first step is to create a data JSON file for stock availability. In the second step use the [Import API](/v1/docs/importing-data#integ-importdata) to import the stock data created. This section focuses on distribution center workflows. However, the same steps apply to stores when NewStore is not the inventory master. For more information on stores, [see below](/v1/docs/tutorial-importing-stock-information#import-stock-information-for-stores). ### Creating stock data As part of the stock import, fulfillment locations are also created for DCs from the `store_mapping` provided: - `store_mapping`: Maps a fulfillment location to a `fulfillment_node_id`. This mapping allows to enable routing from that fulfillment location. - `fulfillment_node_id`: Assigns a `fulfillment_node_id` to the fulfillment location. This `fulfillment_node_id` is used in the fulfillment config to include the fulfillment location in the routing logic for the store. For more information, see [fulfillment config](https://docs.newstore.net/api/integration/order-management/newstore_ff_config_api). > [!NOTE] > Important > > - If the `fulfillment_node_id` property is configured incorrectly, create a new fulfillment location with a different ID. > - For Distribution Centers, set the `store_id` value to `null` in the mapping. The `store_id` value is needed for stores specifically. > - By default, NewStore platform creates a fulfillment location when a new [store](https://docs.newstore.net/api/integration/inventory-management/store_api#tag/Stores/operation/createStore) is created. The fulfillment location has the same id as the store `fulfillment_node_id == store_id` > - To use different ids for fulfillment nodes and stores, reach out to your point of contact at NewStore. For DCs onlyFor DCs and Stores Save the following payload as a file named `availabilities.json` in the `data` folder: For distribution center `DC01`, import 100 items with product ID `1000101` and 50 of the same product for `DC02`. In this example we use `ATP` mode. When this value is specified, any Hard allocation and Soft allocation for items (that have not been shipped) will be added to the import quantity, and the Safety stock will be deducted to calculate the ATP (Available To Promise) for the product. ```json {    "head": {        "store_mapping": [            {                "store_id": null,                "fulfillment_node_id": "DC01"            },            {                "store_id": null,                "fulfillment_node_id": "DC02"            }        ],        "mode": "atp"    },    "items": [        {            "product_id": "1000101",            "quantity": 100,            "fulfillment_node_id": "DC01"        },        {            "product_id": "1000101",            "quantity": 50,            "fulfillment_node_id": "DC02"        }    ] } ``` Save the following payload as a file named `availabilities.json` in the `data` folder: This will prepare stock information for `DC01` to have 50 items of product 1000101. `store1_NYC` will have 100 items of the same product. In this example we use `On Hand` mode. When this value is specified, the import quantity is set as the Stock on hand for the product in the specified fulfillment location in the platform. Hard allocation and soft allocation for items (that have not been shipped) as well as safety stock will be deducted to calculate the ATP (Available To Promise) for the product. ```json {    "head": {        "store_mapping": [            {                "store_id": "store1_NYC",                "fulfillment_node_id": "store1_NYC"            },            {                "store_id": null,                "fulfillment_node_id": "DC01"            }        ],        "mode": "on_hand"    },    "items": [        {            "product_id": "1000101",            "quantity": 100,            "fulfillment_node_id": "store1_NYC"        },        {            "product_id": "1000101",            "quantity": 50,            "fulfillment_node_id": "DC01"        }    ] } ``` The `data` folder should now contain: ```plaintext data ├── availabilities.json ``` The data is ready to be imported. Run the import job as [described here](/v1/docs/tutorial-importing-stock-information#running-the-import). ## Import stock information for Stores When importing stock information for stores, decide whether NewStore is the inventory master or not. - NewStore as inventory master implies that NewStore is the source of truth for stock-on-hand data. The physical inventory data is tracked by NewStore. - If NewStore is not the inventory master, then another system like an ERP tracks the physical stock-on-hand information. ### Use case 1: NewStore is the inventory master > [!NOTE] > Important > > - By default, NewStore platform creates a fulfillment location when a new [store](https://docs.newstore.net/api/integration/inventory-management/store_api#tag/Stores/operation/createStore) is created. The fulfillment location has the same id as the store `fulfillment_node_id == store_id` > - To use different ids for fulfillment nodes, reach out to your point of contact at NewStore before [creating fulfillment locations with custom ids](/v1/docs/tutorial-importing-stock-information#deprecated-creating-a-fulfillment-location-with-a-custom-id) as this is an “on demand” feature. 1. Use [Enable location as inventory master](https://docs.newstore.net/api/integration/order-management/location_api/#operation/enable-location-as-inventory-master) method to set NewStore as the inventory master. A fuflillment location is automatically created for each new store. The id of the fulfillment location is the same as the store id. ```bash curl -X POST "https:///v0/locations/store1_NYC/inventory_master/_enable" \     -H "Authorization: Bearer $AUTH_TOKEN" ``` 2. Import stock into the store via the [Import stock quantities API](https://docs.newstore.net/api/integration/inventory-management/inventory_manager_api#operation/importStock) method. See API documentation for further details. ```bash curl -X POST "https:///v0/i/inventory/stores/store1_NYC/stock_locations/main/stock_import" \     -H "Authorization: Bearer $AUTH_TOKEN" \     -F "count_type=full_count" \     -F "file=@/home/user1/Desktop/stock-quantities.csv" ``` #### (Optional) Creating a fulfillment location with a custom id > [!TIP] > Note > > This only applies if you need to use custom fulfillment location ids for your stores. Custom fulfilment location IDs are an “on demand” feature, please contact your Omnichannel Success Manager if you would like to enable this functionality. If you use custom identifiers for fulfillment locations, you need to perform an availability import with a custom product, quantity set to 0 and a store mapping that reflects the `fulfillment_node_id` that you want to use. The steps below create the `fulfillment_node_id_of_store1_NYC` location and maps it to the store. > [!NOTE] > Important > > Set the product quantity to 0 and use a nonexistent product id as this import will be used to first create the fulfilment location, before the second step of importing stock information for the location. 1. Save the following payload as a file named `availabilities.json` in the `data` folder: ```json {    "head": {        "store_mapping": [            {                "store_id": "store1_NYC",                "fulfillment_node_id": "fulfillment_node_id_of_store1_NYC"            }        ]    },    "items": [        {            "product_id": "1000001",            "quantity": 0,            "fulfillment_node_id": "fulfillment_node_id_of_store1_NYC"        }    ] } ``` 2. Run the import job as [described here](/v1/docs/tutorial-importing-stock-information#running-the-import). 3. You now have a custom `fulfillment_node_id` which is mapped to your store. You can proceed with steps above to enable the location as inventory master and importing stock quantities. ### Use case 2: NewStore is not the inventory master When NewStore is not the inventory master, initial stock quantities can be imported in the same way as for [distribution centers](/v1/docs/tutorial-importing-stock-information#import-stock-information-for-distribution-centers). ## Importing Future inventory For this special business case, import `future inventory` on a scheduled date to fulfill orders. During each stock import, specify either the current `stock on hand` or future inventory to import for a product, **but not both**. Run two separate import jobs to import both stock on hand and future inventory for a product. To import future inventory into the distribution center (`DC01`), use the `future_inventory` property, with the `mode` property set to `atp`. See the [Availability import schema](/v1/docs/importing-data#availabilities-import-file-format). > [!NOTE] > Important > > - NewStore only supports importing future inventory into warehouses or distribution centers, and not stores. > - Import future inventory only as the `future ATP` for the product in the distribution center. > - To update the quantity or date of future inventory for a product, import future inventory again with the updated data. The data from the previous import is overwritten. When importing [product data](/v1/docs/tutorial-importing-products#creating-product-data) for business, we specified that: - 50 items with the product ID `1001001` can be pre-ordered from February 28, 2021 - The product itself is available for sale from March 15, 2021. Import 50 items with the product ID `1001001` as the future ATP, on a scheduled date (March 15, 2021) into the distribution center. This ensures there is enough inventory to fulfill the pre-orders for the product on the date that the product becomes available for sale. 1. Save the following payload as a file named `availabilities.json` in the `data` folder: ```json {    "head": {        "store_mapping": [            {                "store_id": "null",                "fulfillment_node_id": "DC01"            }        ],        "mode": "atp"    },    "items": [        {            "product_id": "1001001",            "fulfillment_node_id": "DC01",            "future_inventory":              {                "quantity": 50,                "date": "2021-03-15"          }        }    ] } ``` The `data` folder should now contain: ```plaintext data ├── availabilities.json ``` The data is ready to be imported. Run the import job as [described here](/v1/docs/tutorial-importing-stock-information#running-the-import). ## Running the import Import the data by creating and running an import job: 1. Zip the `data` folder to `data.zip`: ```bash zip -r data.zip data ``` > [!NOTE] > Important > > On Mac, using the context-menu action might include a `__MACOSX` invisible folder to the zip. This folder breaks the import. 2. Upload it to a URL that NewStore can access. NewStore supports HTTPS URIs and Amazon S3 bucket URIs, as long as NewStore can access them to download the file. 3. Use the [Create import job method](https://docs.newstore.net/api/integration/catalog-sfcc/import-api_api#operation/create-import-job): ```bash curl -X POST "https:///v0/d/import" \   -H "Authorization: Bearer $AUTH_TOKEN" \   -d   '{     "provider": "",     "name": "product_import_20170306",     "source_uri": "https://some-uri-location/data.zip",     "entities": [       "products",       "availabilities",       "prices"     ]   }' ``` NewStore does not support a `full import` for the `availabilities` entity. Full imports are only supported for `products`, `categories`, and `prices`. If a full import job contains the `availabilities` entity, NewStore does not import the `availabilities` data. The import is marked as `failed`. > [!NOTE] > Important > > Be aware that a full import **deletes ALL** of the currently stored data. Only the data freshly imported via the new import job is retained, and this may affect other operations or functionalities in the platform. We **do not** recommend using full imports in your production environment. Performing a full import with multiple catalog/locale combinations in the same zip file can lead to unexpected behavior, and can result in complete loss of data of the affected entities. To hide specific products or categories, the easiest way is to set their `online_to` property to a past date. 4. The job is created and can be started using the [Start import job method](https://docs.newstore.net/api/integration/catalog-sfcc/import-api_api#operation/start-import-job) by providing the URL of the data file to the zip file. ```bash curl -X POST "https:///v0/d/import/{import_id}/start" \     -H "Authorization: Bearer $AUTH_TOKEN" \     -d     '{       "transformed_uri": "https://assets.example.com/integrations/newstore/data.zip"      }' ``` The job is placed in a processing queue. 5. You can check the import job's status with the [Get import job method](https://docs.newstore.net/api/integration/catalog-sfcc/import-api_api#operation/get-import-job) or using NewStore Omnichannel Manager, via `Catalog` > `Imports` > `Catalog imports`. For more information, see [Viewing status of catalog imports](/v1/docs/searching-for-and-filtering-products#viewing-status-of-catalog-imports). Once the job is processed, the status becomes `finished`. > [!NOTE] > Important > > Ensure the [List errors for import method](https://docs.newstore.net/api/integration/catalog-sfcc/import-api_api#operation/list-errors-for-import) returns an empty array. ## Testing the import Now that the data has been imported, you can check the `Stocks Levels` page in NewStore Omnichannel Manager to check that the stock levels reflect the updated stock values from the import. Please be aware that there can be short lag between finishing the import and seeing the new values in NewStore Omnichannel Manager due to internal data replication processes. The lag should be measureable only in minutes. **Related topics** - [Importing data](/v1/docs/importing-data#integ-importdata) - [Import API](https://docs.newstore.net/api/integration/catalog-sfcc/import-api_api) - [Customer API](https://docs.newstore.net/api/integration/catalog-sfcc/consumer-api_api) - [Configuring distribution centers](/v1/docs/configuring-distribution-centers#config-dc) At NewStore, this is called an allocation. Setting aside items at a specific fulfillment location, against a specific order. A Soft allocation is converted to an allocation when the order is routed to a fulfillment location. See Phase 2: Requesting fulfillment to the best fulfillment location. *(Also Reservation)* Earmarking goods for a configurable amount of time, at a store or Distribution center , after an order is placed in the platform. A reservation expires if the order is not completed when the configured time has elapsed. When the item is routed, the reservation is changed to an Hard allocation. See About order routing. The quantity of items that cannot be promised for delivery and is set aside as a safety measure against overselling. See Monitoring stock levels. *(Also On hand stock)* This term outside NewStore, refers to the quantity of a stock-keeping unit that is physically available to sell, at a location, including Hard allocation , Soft allocation , and Safety stock. About inventory management that is scheduled to arrive into the Fulfillment location on a future date. Once the items arrive at the fulfillment location, they are added to the Stock on hand for the product at the location and are not considered future inventory anymore. In NewStore Omnichannel Cloud, future inventory for a product can be set using a stock import. See Future inventory.