Tutorial: Importing stock information

After you follow the previous product import tutorial , you now have product(s) available to sell in your business.

In this tutorial, we will 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.

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 to understand how the Import API works.

We assume that you have an authentication token stored in the AUTH_TOKEN variable. Retrieve one with the following call:

export AUTH_TOKEN=$(curl -s <url>/v0/token -d \
"grant_type=password&username=<myusername>&password=<mypassword>" | jq -r .access_token)

Pre-requisites

Important

Before going through the import steps, ensure that you have created a store and imported products .

You may or may not have enabled NewStore as inventory master for your business. Follow the instructions provided for the use case that best describes your operational mode with NewStore.

Use case 1: NewStore is not the inventory master

At the end of this tutorial, you should have set up a business with one warehouse (DC01) and one store (store1_NYC) that can fulfill orders. NewStore is not the inventory master in these fulfillment locations.

Important

Read the integration guide to understand how the Import API works.

Let's do this import process in 2 steps:

• Creating the stock data
• Importing the newly created stock data

The first step is to create a data JSON file for stock availability. In the second step we will use the Import API to import the stock data we have created.

Creating stock data

This tutorial assumes that an ERP is inventory master in the distribution center. To import stock when NewStore is inventory master in the store, see this guide .

This import step only contains stock information. To represent it, we use this stock schema.

For our warehouse (DC01), let's import 100 items with product ID 1000101 as the stock on hand for the product in the warehouse and 50 for our store store1_NYC.

Creating warehouses

As part of the stock import, also create a map of stores and DC as fulfillment nodes:

• fulfillment_node_id: Assigns a fulfillment_node_id to the store. The fulfillment_node_id is what is used in the fulfillment config to include the store in the routing logic for your store. See fulfillment config.
• store_mapping: Maps a store to a fulfillment_node_id. This mapping allows you to enable routing from that store.

Important

• If you provide a wrong value for the fulfillment_node_id property, you need to create a new one with a different name.
• Ensure that you do not use the value of the store_id property as the value of the fulfillment_node_id property. Using the value of the store_id property causes errors that cannot be fixed with a new import.

1. Save the following payload as a file named availabilities.json in the data folder:

   {
       "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": "DC01",
           },
           {
               "product_id": "1000101",
               "quantity": 50,
               "fulfillment_node_id": "store1_NYC",
           }
       ]
   }

Your data folder should now contain:

data
├── availabilities.json

We are ready to import the data. See Running the import .

To understand how to manage warehouses, see Configuring distribution centers .

Use case 2: Importing future inventory

For this special business case, we will import future inventory on a scheduled date to fulfill orders. During each stock import, you can specify either the current stock on hand or future inventory to import for a product, but not both.

Run 2 separate import jobs to import both stock on hand and future inventory for a product.

To import future inventory into the warehouse (DC01), we will use the future_inventory property, with the mode property set to atp. See the stock schema.

Important

• NewStore only supports importing future inventory into warehouses or DCs, and not stores.
• You can import future inventory only as the future ATP for the product in the warehouse.
• 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 for our business, we had 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.

So, let's import 50 items with the product ID 1001001 as the future ATP, on a scheduled date (March 15, 2021) into the warehouse. This ensures that 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:

   {
       "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"
             }
           }
       ]
   }

Your data folder should now contain:

data
├── availabilities.json

We are now ready to import the data. See Running the import .

Use case 3: NewStore is inventory master

This tutorial describes how to use NewStore to import stock and manage your store's inventory.

1. Assuming you have already created a store, map the store to a location by calling the For this, make a POST request to {{environment-url}}/v0/d/import/availability?full=false. See this JSON payload example for the request body.

   {
       "head": {
           "store_mapping": [
               {
                   "store_id": "store1_NYC",
                   "fulfillment_node_id": "fulfillment_node_id_of_store1_NYC"
               }
           ],
           "mode": "atp"
       },
       "items": [{"product_id": "1000001", "quantity": 10, "fulfillment_node_id": "fulfillment_node_id_of_store1_NYC" }]
   }

   The fulfillment_node_id_of_store1_NYC represents the location identifier that will be used to route orders. The POST request creates the fulfillment_node_id_of_store1_NYC location and maps it to the store (store1_NYC).

2. Use the Enable location as inventory master method to set NewStore as inventory master for the fulfillment_node_id_of_store1_NYC store.

3. Import stock into the store (store1_NYC) via the Import stock quantities API method.

Running the import

Let's import the data by creating and running an import job:

1. Zip the data folder to data.zip:

   zip -r data.zip data

   Important

   On Mac, using the context-menu action might include a __MACOSX invisible folder to the zip. This folder will break 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:

   curl -X POST "https://<url>/v0/d/import" \
      -H "Authorization: string" \
      -d
      '{
        "provider": "<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.

   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 to use 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.

4. The job is created and can be started using the Start import job method by providing the URL of the data file to the zip file.

   curl -X POST "https://<url>/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 or using NewStore Omnichannel Manager, via Catalog > Imports > Catalog imports. For more information, see Viewing status of catalog imports .

   Once the job is processed, its status becomes finished.

6. Important

   Ensure the List errors for import method returns an empty array.

   If there are errors for the import job, see Troubleshooting import errors .

Testing the import

Now that the data has been imported, you can check the Stocks Levels page in NewStore Omnichannel Manager.

The import is complete.

Related topics

• Importing data
• Import API
• Customer API
• Configuring distribution centers