Skip to main content
API docs by Redocly

Import Data API (v0)

Download OpenAPI specification:Download

Use this resource to import products, categories, price books, and stock on hand into NewStore. For more information on how to prepare your data and import it, see the tutorial or the integration guide in our documentation.

Note: Before you import data, ensure that you have created a store.

As indicated in the documentation, to import the data, create a zip file from the folder that contains the JSON files for the entities you are importing. Upload the zip file to a URI that NewStore can access.

Important:

  • We recommend importing data in a single import job, via a single file that does not exceed 500 MB. However, if an import job needs to be broken down into multiple imports, ensure that each new import job is run after a 5 minute interval, where product data should not exceed 500 MB, and all other entities should not exceed 80 MB.
  • The default limit for creating import jobs is 20 for all import jobs except for product imports, the limit for which is 10. If you reach the limit with current open import jobs, NewStore keeps them in the received state and API responds with a 429 error. We recommend you to either start your import jobs in the received state or mark them as failed using the Set import job status to failed method. Keeping them in the received or waiting state adds to the total number of import jobs considered against the limit.
  • When an import job is finished, the system takes some time to process the data. Usually this means only a few minutes, but in rare cases, when the system is under pressure it can take 24-48 hours to make the imported information available.

NewStore supports HTTPS URIs and Amazon S3 bucket URIs as long as we can access them to download the files. You should consider longer TTL (time to live) for such files, at least in the range of days, because these files are not immediately downloaded but internally queued for import. It may happen that during high traffic on the platform, your import might be delayed even for hours. So having a longer TTL can prevent failure in these imports.

This API allows you to import the following entities.

Note: If you decide to import each entity separately, create import jobs for each data entity in this sequence: Products > Stock > Pricebooks > Categories (optional)

Server requirements for image download

NewStore provides an option to specify an image download URL in products or categories to be imported. We expects that the server pointed in the URL meets following service-level objectives with each import:

  • 99.99 % server response HTTP codes should be HTTP 200.
  • 99.99 % latency of server responses should be under 10 seconds.
  • When a server cannot respond in time, it should return HTTP 429. NewStore will make the best effort to retry the image download.

NewStore attempts up to 5 continuous GET requests. Each request with 20s timeout to read whole response. Response HTTP 429 is considered as retryable error. Each retry is delayed by 0.5s as backoff. All non-200, 4xx, and 5xx HTTP status codes are considered unrecoverable and will lead to missing images in the imported products and categories.

As network between NewStore and image server is volatile, sometimes few images won't be downloaded. The image failure feedback is logged in the import error page. So it is advised to setup monitoring and retry import of products and categories with failed images. For products with no images in the app, the Newstore default product image will be used. As a result, such products are still sellable but store associates will have problems identifying them in the app.

NewStore does caching of all downloaded images and requests only new images. So in case of duplicate images, only new images will be downloaded from the image server.

Every request contains:

  • User-Agent header identifying NewStore requests (it can be used to simply identify NewStore requests in firewalls). The current value to identify NewStore requests in NewStoreCatalogImageStore/1.0.

To find and fix these errors, see the Troubleshooting Guide.

Products

The only way you can create or update products, is by importing them into NewStore.

A product in NewStore usually refers to a stock-keeping unit (SKU) as product_id but can be replaced with any other unique identifier.

Products are imported into a shop for a specific locale. A shop represents the hierarchical entity into which you import products and categories. It is not a physical store.

A variant_group_id connects all the variants of a product. Each product must be unique to a variant group in a shop, and cannot be assigned to multiple variant groups. Even if a product has only one variant, create a variant group to contain the single product variant.

When importing data to multiple fulfillment locations in your business, use the availabilities_store_ids property to specify the ID of the stores or DCs where you want to import data.

If you are importing more than one category, use the categories > is_main property to specify the main category for the product. This category is displayed against relevant products in the Catalog tab in Newstore Omnichannel Manager. For more information, see the guide.

The product details that you provide during import determine the product attributes that are displayed in NewStore applications and the information that is included in reports. Missing information that is not required during an import might still impact your business workflow, based on your integrations.

For example, Toby Sweater, Black, Size 6, and Toby Sweater Beige, Size 6, are variants and have different SKUs. They are created as two separate products and in this example, they belong to the same variant group (variant_group_id).

To enable pre-orders for a product, set the preorder_start property to the date when pre-orders should begin.

For more information, see:

Categories

The only way you can create or update product categories, is by importing them into NewStore.

A category refers to the hierarchy applied to your products, in order to organize them. Product categories may differ across different sales channels. For example, the category for Toby Sweater Black Size 6 could be Shop > Clothing or Featured > Winter.

Categories are imported into a shop, and for a specific locale.

Important: Since categories are already imported with the product import, importing categories separately is only required if you want them to be accessible via the List categories method. Such an import will also allow you to add pictures and a description for each category and enable sorting sub-categories.

For more information, see:

Price books

The only way you can create or update price books is by importing them into NewStore.

A price book is a collection of prices for products, in a specific currency. You can import multiple price books. For example, each sales channel can have a different price book.

Important: Ensure that you specify the correct number of decimal places for monetary values of prices, according to the specified currency. For example, if the currency is specified as USD and the price has more than 2 decimal places, it is considered as invalid by the platform.

For more information, see pricing dependencies on currency.

To understand the the JSON schema for importing price books, see JSON schema for price books. Do not use this method to import price books. This is only documentation of the schema.

To import your price books, use the import process described in Importing data.

Stock

The only way you can create or update stock on hand, is by importing it into NewStore.

Stock refers to the total inventory, at a particular time. Unlike products, you import stock into a fulfillment location (distribution center or store), and not into a shop.

Note: Ensure that you provide the correct value for the fulfillment_node_id property during the stock import. Deleting a fulfillment_node_id with a wrong value is currently not possible.

To specify if the quantity you are importing for a product is the new ATP or stock on hand for the product at the specified fulfillment location, use the mode property.

To import future inventory at the fulfillment location, use the future_inventory property, with the mode property set to atp.

For more information, see:

Distribution Centers

There are two ways to create a distribution center (DC) or warehouse for your business:

  • When you import stock, the location of the stock is automatically created as a fulfillment_node_id in NewStore. To indicate that the fulfillment location in fulfillment_node_id is a DC, ensure that the store_id is set to null. To configure a DC that is created using this method, contact the support team.

  • Use this tutorial to create and configure a DC on your own.

For more information, see:

List import jobs

Returns a list of import jobs.

Note: Import jobs are deleted after 30 days and not returned by this method anymore.**

Authorizations:
newStoreAccessToken
query Parameters
filter
string

The field to filter and its filter value(s). The field is specified in subscript notation and its values are comma separated. When the value is expression of a range, the min and max range are separated by the pipe character (|).

Examples:

  1. ?filter[state]=failed
  2. ?filter[state]=processing,finished
  3. ?filter[entities]=products
  4. ?filter[completed_at]=2016-10-01|2016-10-15
  5. ?filter[state]=processing,finished&filter[completed_at]=2016-10-01|2016-10-15
offset
integer >= 0
Default: 0

The page offset.

count
integer >= 1
Default: 10

The number of requested import jobs.

sort
string
Example: sort=completed_at|desc

Sorts the returned values. Takes two values separated by the pipe character (|), the field to sort and the sort order.

Responses

Response samples

Content type
application/json
{
  • "pagination_info": {},
  • "items": [
    ]
}

Create import job

Creates an import job to import data into NewStore. The job will not be processed automatically. To process it, use the Start import job method.

Important: The import job's source_uri property must point to a ZIP file for each entity. The uncompressed file size must be lower than 240 MB for products. For other import entities, the file size must be lower than 80 MB.

Authorizations:
newStoreAccessToken
Request Body schema: application/json
provider
required
string

The name of the provider of the data, for example, Salesforce Commerce Cloud.

source_uri
required
string <uri>

File location of the original file from the provider (only for information). The uncompressed file size per entity must be lower than 80 MB.

name
string

The name of the job.

type
string

DEPRECATED: The type of the job. Use the 'entities' property instead.

entities
required
Array of strings unique
Items Enum: "products" "categories" "availabilities" "prices" "dwre_orders"

The type of data provided in this request. The possible values of this fields also determine the naming convention of the JSON files you might import in a ZIP file via the 'POST /import/{import_id}/start' method.

full
boolean
Default: false

Determines if the job is a full or a partial import. A full import deletes the existing data and imports the new data. A partial import adds data on top of existing data.

.. important:: |nes| does not support 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, |nes| does not import the availabilities data.

shop
string

The shop the import is being made for. Required when multiple imports are desired at the same time.

locale
string

The locale the import is being made for. Required when multiple imports are desired at the same time.

availabilities_store_ids
Array of strings unique

The stores' id the import is being made for. Required when multiple availabilities imports are desired at the same time.

Responses

Request samples

Content type
application/json
{
  • "provider": "string",
  • "source_uri": "http://example.com",
  • "name": "string",
  • "type": "string",
  • "entities": [
    ],
  • "full": false,
  • "shop": "string",
  • "locale": "string",
  • "availabilities_store_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "string"
}

Get import job

Retrieves the status information of the specified import job. See the list of statuses for more information. You can also see the status of an import job in NewStore Omnichannel Manager. See this guide for more information.

Important: The finished status does not mean that there were no errors.

To know if the import was successful, use the List import errors method and check if it returns an empty array.

Related methods:

Note: Import jobs are deleted after 30 days and not returned by this method anymore.**

Authorizations:
newStoreAccessToken
path Parameters
import_id
required
string

Identifier received in the response of Create import job method

Responses

Response samples

Content type
application/json
{
  • "import_id": "string",
  • "source": "string",
  • "provider": "string",
  • "entities": [
    ],
  • "source_uri": "string",
  • "transformed_uri": "string",
  • "revision": 0,
  • "name": "string",
  • "received_at": "2019-08-24T14:15:22Z",
  • "completed_at": "2019-08-24T14:15:22Z",
  • "state": "received",
  • "reason": "string",
  • "full": false
}

Start import job

Adds the import job to the processing queue. It is automatically processed when it reaches the first position of the queue.

After you call this method, the following updates happen:

1- The state of the job is automatically updated:

  • While the job is waiting to be processed, state is set to waiting, and the job starts when previous waiting jobs have been processed.
  • When the job is being processed, the state is set to processing.

2- The import job transformed_uri property is set. This field must point to a ZIP file containing all the JSON files to import. This field cannot point to a JSON file.

Each JSON file must:

  • Contain only one type of entity, formatted as described in the /products, /availability, /categories and /prices methods.

  • Have the entity type it describes ("products", "categories", "availabilities", "prices") in its path/filename.

    For example, if you have a file containing the prices of your products, you can name it prices_1.json.

Related methods:

Note: Import jobs are deleted after 30 days and not handled by this method anymore.**

Authorizations:
newStoreAccessToken
path Parameters
import_id
required
string

Identifier received in the response of Create import job method

Request Body schema: application/json
transformed_uri
required
string <uri>

URI to the ZIP file containing the source files in the required NewStore JSON format. This field cannot be set to a different value once it's been set the first time. Each JSON file in the ZIP file must contain the entity type it represents in its filename. For example, if you have a file for prices, it must contain 'prices' in its filename. The list of entity names can be found in the 'Create import job' method documentation. This URI must be either an HTTPS URIs or an Amazon S3 bucket URI, and NewStore must have access to it.

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "import_id": "string",
  • "source": "string",
  • "provider": "string",
  • "entities": [
    ],
  • "source_uri": "string",
  • "transformed_uri": "string",
  • "revision": 0,
  • "name": "string",
  • "received_at": "2019-08-24T14:15:22Z",
  • "completed_at": "2019-08-24T14:15:22Z",
  • "state": "received",
  • "reason": "string",
  • "full": false,
  • "shop": "string",
  • "locale": "string",
  • "availabilities_store_ids": [
    ],
  • "version": 0,
  • "all_import_requests_published": true,
  • "cleaned_entities": [
    ]
}

List import errors

Retrieves a list of errors for the specified import job. You can also see a list of errors for an import job in NewStore Omnichannel Manager. See this guide for more information.

Note: Import jobs are deleted after 30 days and not returned by this method anymore.**

Authorizations:
newStoreAccessToken
path Parameters
import_id
required
string

Identifier received in the response of Create import job method

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Save import errors

Saves import errors to the database. Use it to report errors occurring during an import. For example, transformation services, integration scripts such as lambda functions can call this method to report errors.

Note: Import jobs are deleted after 30 days and not handled by this method anymore.**

Authorizations:
newStoreAccessToken
path Parameters
import_id
required
string

Identifier received in the response of Create import job method

Request Body schema: application/json
Array
error_id
required
string <uuid>

A random uuid that identify this error

entity_type
required
string
Enum: "products" "categories" "availabilities" "prices"

The import entity for which this error occurred.

entity_id
required
string [ 1 .. 255 ] characters

The ID of the import item which failed to be imported.

reason
required
string non-empty

The error message or reason why an item failed to be imported.

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "acknowledged": true
}

Set import job status to failed

Sets the specified import job's status to failed for the specified reason.

Related methods:

Note: Import jobs are deleted after 30 days and not handled by this method anymore.**

Authorizations:
newStoreAccessToken
path Parameters
import_id
required
string

Identifier received in the response of Create import job method

Request Body schema: application/json
reason
required
string

The reason why the import job failed.,

Responses

Request samples

Content type
application/json
{
  • "reason": "incorrect data"
}

Response samples

Content type
application/json
{
  • "import_id": "string",
  • "source": "string",
  • "provider": "string",
  • "entities": [
    ],
  • "source_uri": "string",
  • "transformed_uri": "string",
  • "revision": 0,
  • "name": "string",
  • "received_at": "2019-08-24T14:15:22Z",
  • "completed_at": "2019-08-24T14:15:22Z",
  • "state": "received",
  • "reason": "string",
  • "full": false
}

List import chunks

Retrieves chunk information for the specified import job.

A import job is split into chunks of items. Use this method to get information about each of these chunks. Chunks are only created once the import job has reached the processing status.

Related methods:

Note: Chunks are deleted after 30 days and not returned by this method anymore.**

Authorizations:
newStoreAccessToken
path Parameters
import_id
required
string

Identifier received in the response of Create import job method

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}