This article explains how to prepare an import file for the "products" scope.
Records in the "products" scope represent items which can be purchased. "Products" are then related to "orders" (representing receipts) via "ordersitems" (individual items in each receipt).
/!\ Note that "products" is one of the scopes which can be updated: existing data can be changed by future imports.
- Basic knowledge of the CSV format and UTF-8 encoding.
- A UTF-8-enabled text editor.
- A spreadsheet software.
- The sub-sequence must be defined in the config file under the “products” scope.
Preparation of a products file
Check the file you are preparing to see if it contains all the information you want to import. Use your spreadsheet software to arrange columns and remove those you cannot (or do not want to) import. Remember always to save as (or export to) a CSV file with UTF-8 encoding without BOM and use semicolons (";") to separate columns.
Use your favorite text editor to open and modify the CSV import file.
Header and Columns
The first row of the file is the header. Make sure that it contains only column names, or the import will fail.
The following columns are available in "products" files:
- product_id -- the external identifier of the product; this column is mandatory and must be unique for each product.
- name -- the name of the product which will be displayed in Splio.
- brand -- the brand of the product.
- description -- the description of the product - additional information that will be visible in Splio.
- price -- the nominal price of the product. It is always a number with 2 decimal places (e.g., 2.50), denominated in the default currency of the Splio universe.
- category -- the name of the category assigned to the product.
- img_url -- the URL of an image used to illustrate the product.
- sku -- the product's stock keeping unit (SKU).
- A custom column, if defined for products in your Splio universe.
Note that all the columns referred to system fields are always lowercase.
Remember that the import will fail if you do not include the mandatory column (product_id) or if you use a column which Splio cannot recognize (that is, neither one of the default columns or a properly defined custom column).
Important: please note that when uploading your product prices, you must enter two decimals after the dot (i.e 10.99).
Example of a file
A short file containing some animal-related products may look like this:
product_id;name;brand;price "0013130002004";"Dog Treats";"Milk Bone";"182.49" "8003299918256";"Tigrito Cat Bowl";"Alessi";"38.50" "0871864006190";"Hot Diggity Dog Dog Toy Size Medium";"Petstages";"85.25" "0721343632993";"Maximum Absorbency Dog Puppy Pads Size 100 Package;Zanies";"119.91" "0045663188931";"Dog Diaper Garment Size Medium";"Topdawg Pet Supply";"115.61"
The example uses four standard columns: product_id, name, brand, and price. The values corresponding to each column are located in the following rows.
Name your file
Save your file under a name composed of the universe name, scope ("products"), sub-sequence, and current date. For example:
This filename belongs to the universe "myuniverse", sub-sequence "zoo" defined for products, and is dated April 16, 2018.
If you wish to know more, consult the File Naming and Grouping guide.
You can now upload the file to SFTP/FTPS.
This part of the document contains additional information which supplements the guide above and provides more detail.
|Encoding||UTF-8 without BOM|
|Format||CSV (no multiline)|
|Column separator||; (semicolon)|
|Text qualifier||" (double quote, optional)|
|Escape character||\ (backslash)|
|End of line||\n or \r\n|
|Decimal separator||. (dot)|
The table below contains detailed information about all columns (fields) in the "products" scope.
/!\ Remember that all column names are case sensitive. For this reason, default names are all lowercase.
|Column||Mandatory||Data Type / Maximum length||Description|
|product_id||Yes||Text (max. 50 characters)||This column should contain the external identifier of the imported product. Being the primary key of the "products" table, this column is mandatory. Therefore, if it is missing, the import will be aborted. Also, Splio will skip all lines which do not provide a "product_id" value.|
|name||Yes||Text (max. 120 characters)||The name of the product|
|brand||No||Text (max. 120 characters)||Represents the name of the product's brand.|
|description||No||Text (max. 120 characters)||Contains a short description of the product (make sure you are aware of the restricted field size).|
|price||No||Decimal, "." (dot) as decimal separator. Always expressed in the default currency of your universe.||The price of the product.|
|category||No||Text (max. 120 characters)||The category of the product.|
|img_url||No||Text (max. 65k characters)||The URL of an image of the product.|
|sku||No||Text (max. 120 characters)||The SKU of the product.|
|Product custom field||No||Text (max. 255 characters)||See below|
The import feature in Splio allows using custom fields which have been configured in your universe. To include a custom field, use either its name as the column header or the lowercase letter "c" followed by its numerical id.
For example, if you have a field called "category" in your "products" table, and its id is 2, you can use either "category" or "c2" as the name of the column.
Bear in mind that if Splio cannot recognize the name of a column, it will not import the file.
The following information is made available by Splio after import.
- Whether the import was aborted or not and, if aborted, the reason (unknown column, missing external id column, undeclared custom field)
- The number of lines treated (imported+skipped)/imported/skipped
- The number of new and updated records
- The reason each line was skipped (product_id NULL, too many/not enough columns)
Normally, a log file will be available in the same repository where the import file was uploaded.