Importing Products
Importing Products
Contents
- Introduction
- Product File Set Overview
- Product List File
- Variant List File
- Naming Files
- File Contents
- Version Tracking
Introduction
The Spaaza product import file set consists of two CSV files uploaded at intervals to manage product and variant catalogue information within the Spaaza platform.
Product File Set Overview
The file set consists of the following 2 files in CSV format:
- Product List file - Contains product information
- Variant List file - Contains product variant and barcode information
Product List File
The Product List file provides a list of products/items sold by the retailer. Each row in the CSV file corresponds to a single product.
The columns in the Product List file correspond to the parameters of the add-product API endpoint. Refer to that endpoint documentation for the full list of available fields and their descriptions.
CSV-specific differences from the API:
| Column Name | Description |
|---|---|
| id | (integer, conditional) The Spaaza product ID. Either id or owner_code must be provided. Use id when updating an existing product |
| update_if_exists | (boolean, optional) Can be specified per row to control update behaviour. When true, updates an existing product with matching identifier. Defaults to false unless the --update-if-exists flag is set on the import script |
Sample product list file:
owner_code,name,description,price,brand,category,web_url,is_promotional,cost_price,unit
PROD001,Super Tank Top,Tank top for summer wear,25.00,TANK TOPTASTIC,Clothing > Tops > Tank Tops,http://www.example.com/tank_top.html,false,17.40,item
PROD002,Loose Leaf Ceylon Tea,Loose leaf tea from Sri Lanka,12.50,ACME TEAS,Loose Leaf Teas,http://www.example.com/ceylon_tea.html,false,8.00,g
Download sample product list file
Variant List File
The Variant List file lists all product variants including sizes, colours, and barcodes. Each row in the CSV file corresponds to a single barcode entry for a product variant.
The columns in the Variant List file correspond to the parameters of the add-product-variant API endpoint. Refer to that endpoint documentation for the full list of available fields and their descriptions.
CSV-specific differences from the API:
| Column Name | Description |
|---|---|
| product_variant_owner_code | (string, optional) A unique identifier for the product variant within the chain. This field is named owner_code in the API response. Either product_variant_owner_code or owner_code can be used as the column name. When blank or omitted, the importer targets the variant with a blank owner code on the specified product |
| owner_code | (string, optional) Alternative column name for product_variant_owner_code. Both column names are accepted by the importer |
| barcode | (string, mandatory) A single barcode value for the product variant. Unlike the API which accepts an array of barcodes, the CSV file contains one barcode per row. Multiple barcodes for the same variant require multiple rows |
| update_if_exists | (boolean, optional) Can be specified per row to control update behaviour. When true, updates an existing variant with matching identifier. Defaults to false unless the --update-if-exists flag is set on the import script |
When the owner code column is blank or omitted, the importer will attempt to find and update a variant with a blank owner code on the specified product. If multiple variants exist with blank owner codes for the same product, an error will be returned.
Sample variant list file:
product_id,product_variant_owner_code,barcode,name,price,colour,size
456,VAR001,2000042436011,Navy Tank Top Small,25.00,Navy,S
456,VAR001,2000042436012,Navy Tank Top Small,25.00,Navy,S
456,VAR002,2000042436013,Navy Tank Top Medium,25.00,Navy,M
In the example above, variant VAR001 has two barcodes (2000042436011 and 2000042436012), each on a separate row.
Download sample variant list file
Naming Files
Product files follow this naming convention:
<filetype>_<YYYYMMDD>_<HHMMSS>.csv
The filetype prefixes are:
- Product List file:
productlist - Variant List file:
variantlist
Where:
<YYYYMMDD>= date (year, month, day)<HHMMSS>= time (hours, minutes, seconds, 24-hour clock)
Example filenames:
productlist_20251024_100000.csv
variantlist_20251024_100000.csv
When uploading files, both files in a set must use exactly the same date and time in the filename. The Spaaza importer processes files in increasing order of date and time of creation.
File Contents
Product files are valid CSVs with:
- Comma separators
- Double quotes (
") as escape characters - First row = column headers (lowercase, matching API parameter names)
- UTF-8 encoding in Unix format (LF line endings)
Column names in the CSV file should use lowercase and match the API parameter names (e.g., owner_code, name, price).
We recommend using a CSV validator to validate files before upload.
Version Tracking
| Date | Version Changes |
|---|---|
| 2016-10-04 | Initial documentation version documenting existing feed |
| 2016-12-04 | Added product category, webshop URL and unit, and variant image URL |
| 2017-03-24 | Clarified product category information |
| 2017-09-27 | Updated definitions and removed extraneous fields in line with latest importer code |
| 2018-01-30 | Updated to explicitly state decimal separator |
| 2019-07-16 | Added product cost price and category fields |
| 2023-07-13 | Updated product field descriptions for clarity |
| 2025-10-24 | Updated SOH file name to "Variant List file". Separated store import documentation into dedicated page |
| 2026-01-14 | Rewrote documentation to reference add-product and add-product-variant API endpoints. Updated CSV format to use lowercase column names matching API parameters |
| 2026-01-30 | Updated variant list documentation: product_variant_owner_code is now optional, owner_code accepted as alternative column name, blank owner code targets variants with blank owner code |