Spaaza Product Feed Import

Contents

• Introduction
• Feed File Overview
• Spaaza S3 Bucket
• Naming and Uploading Feed Files
• Resynchronising the Feed
• File Contents
  • Branch File
  • Product List File
  • Variant and Stock File

Introduction

The Spaaza product feed file set consists of a set of three CSV files uploaded at intervals to an Amazon S3 bucket. This feed enables retailers to maintain current product catalog information, store locations, and inventory levels within the Spaaza platform.

Feed File Overview

The feed consists of the following 3 files in CSV format:

1. Branch file

This file describes physical store branches in a retail chain including branch name, address and retailer-specific branch number. It should also include a head office location. This file always includes all branches in the chain.

2. Product List file

This file provides a list of products/items sold by the retailer and includes information for each product such as product name, brand, season, base price, image URL and identifier codes. This file always includes all products carried by a retailer.

3. Variant and Stock file

This file serves both to list all variants for products/items including sizes, colours and barcodes, as well as allowing the listing of stock in individual branches should a retailer choose to do so. In many cases retailers choose not to use this file to record stock levels, in which case one entry for each barcode found in the retail sales environment is listed. This file is incremental - only changes since the last upload are shown except when resynchronising the feed (see section below).

Spaaza S3 Bucket

Spaaza provides an Amazon AWS identifier and credentials for an S3 bucket to which the feed files can be uploaded on a frequent basis. The feed URL is similar to the following:

s3://feed-spaaza-product-stock-retailername

Naming and Uploading Feed Files

Feed files follow a naming convention which includes a stem specifying the file designator, followed by the valid date and then time of creation. The name, date and time are separated by underscores. The feed file is suffixed with the .csv extension.

When an upload happens, all three files (branch file, product list file and variant/stock file) must be uploaded in a set using exactly the same date and time of creation in the filename. The Spaaza importer then picks up the files from Amazon S3 and processes them in increasing order of date and time of creation.

The following is an example of correct naming of 3 feed files:

branch_20170914_140236.csv
productlist_20170914_140236.csv
soh_20170914_140236.csv

If files do not contain a valid date or time or the dates and times do not match, the importer will error.

Resynchronising the Feed

Should the feed fall out of synchronisation, this can be corrected by sending a full variant and stock file containing all variants and stock items.

File Contents

Feed files contain correctly formatted CSV content, with a comma separator and a double quotation mark (") used as an escape character. The first row in the file contains column headings in upper case. It is possible to validate a CSV file online or with a package such as ‘csvfix’.

This section describes the fields in each file and includes some details of how the files are linked to each other by branch code and product identifier.

As the feed definition is upgraded, new fields are added at end of the field list for each file. This ensures files in the old format can still be used by the importer, but means it’s necessary to pay close attention to the order in which fields are sent, and that related fields may not always appear in consecutive order in the feed files.

Branch file

The branch file contains the following column headings:

"BRANCH NUMBER","BRANCH NAME","BRANCH ADDRESS 1","BRANCH ADDRESS 2","BRANCH ADDRESS 3",
"BRANCH POSTALCODE","BRANCH COUNTRYCODE","LATITUDE","LONGITUDE","GOOGLE PLACE ID",
"PHONE NUMBER","TOWNCITY","REGION","SHUTDOWN"

An example of row in this file looks like this:

"ANY_1027","ACME Retailer Anytown","Mall Unit #14","Anytown Mall","347 Ancient Heroes Avenue",
"1000CA","NL","54.24677","4.25666","ChIJFVeMnoQJxkcRh95gA0gNHuc","+31 20 555 1234",
"Anytown","North Anyregion",0

Sample branch file data:

Download sample branch file

Field descriptions:

Product List File

The product list file contains the following column headings:

"PRODUCT ID","PRODUCT CODE","PRODUCT NAME","PRODUCT DESCRIPTION","SELL INCL","SUPPLIER",
"BRAND","GENDER","RANGE","BARCODE","CREATED DATE","SEASON","DELETED",
"PRODUCT WEBSHOP URL","PRODUCT UNIT","COST_PRICE","CATEGORY"

An example row in the product list file looks like this:

4062,"O-62716","SUPER TANK TOP","BLUE TANK TOP FOR SUMMER WEAR",25.00,
"ACME FASHION DISTRIBUTOR","TANK TOPTASTIC","F","Tops","3123424324322","2016-01-28",
"WINTER 2016",0,"http://www.example.com/tank_top_42.html","Item","17.40",
"Clothing > Tops > Tank Tops"

Sample product list file data:

Download sample product list file

Field descriptions:

Variant and Stock File

The SOH file contains the following column headings:

"PRODUCT ID","PRODUCT CODE","BNO","BRANCH","SIZE","COLOUR","SOH","SELL INCL",
"BARCODE","IMAGE URL"

An example row in the file looks like this:

4062,"O-62716","1027","ACME Retailer Anytown","9","Blue",5,25.00,"400819001140",
"https://sampleshop.example.com/products/4062/full_image.jpg"

Should the retailer choose not to list stock in all stores, each variant or barcode carried should be listed as “in stock” in a head office branch. Removing stock is done simply by setting the SOH field to 0.

Sample variant and stock file data:

Download sample variant and stock file

Field descriptions: