Importing Product Catalog Files

Overview

This guide details the process for importing various file types into the Product Information Management (PIM) system to manage categories, attributes, products, and related data. Each section corresponds to a specific file type, providing field descriptions, import requirements, and best practices to ensure successful data uploads. Use this documentation to prepare and import files accurately via the PIM interface at https://pim.bettercommerce.io.

Navigate to Import Files

Go to Dashboard → Catalog → Imports
Select the appropriate file type from the dropdown (e.g., Category, Product, CustomAttribute).
Upload the prepared CSV file and monitor the import status in the All Activity logs (Dashboard → Stats → Data Flows → All Activity).

Note: Ensure files are in CSV format with headers matching the field names exactly as specified.

1. Category Upload (CategoryUploadSampleFile)

Overview

Imports category details, including hierarchy and product family associations.

Fields

Column	Required	Possible Values	Description	Example
CategoryCode	Yes	e.g., Lower	Unique identifier for the category, used in the backend.	Lower
CategoryName	Yes	e.g., Lower	Display name of the category for the website.	Lower
ParentCategoryCode	Yes	e.g., Clothing	Code of the parent category, linking this category as its child.	Clothing
ProductFamilyId	No	e.g., Apparels	Optional identifier for a product family encompassing multiple categories.	Apparels

Best Practices

Ensure CategoryCode is unique across all categories.
Verify ParentCategoryCode references an existing category.
Create product families in the PIM system before assigning ProductFamilyId.
Check import status in All Activity → Imports for errors.

Use Cases

Creating new categories for product organization.
Establishing category hierarchies for navigation.

2. Category Image (CategoryImage)

Overview

Manages images associated with categories, controlling their status and display order.

Fields

Column	Required	Possible Values	Description	Example
Action	Yes	Add, Delete	Action to perform on the image (add or delete).	Add
Active	Yes	0, 1	Indicates if the image is active (1) or inactive (0).	1
CategoryCode	Yes		Unique identifier for the linked category.
Description	No		Textual description of the image or category.
DisplayOrder	No		Order in which the image appears (lower numbers appear first).
ImageName	Yes	e.g., category_image.jpg	Filename of the image, including extension.	category_image.jpg

Best Practices

Use valid image filenames with extensions (e.g., .jpg, .png).
Ensure CategoryCode matches an existing category.
Monitor import logs for file format or linkage errors.

Use Cases

Adding category images for enhanced website visuals.
Updating or removing outdated category images.

3. Custom Attribute Master (CustomAttributeMaster)

Overview

Defines custom attributes for products, controlling their behavior and visibility.

Fields

Column	Required	Possible Values	Description	Example
AttributeCode	Yes	e.g., product.fabric	Unique identifier for the attribute, used in the backend.	product.fabric
AttributeName	Yes	e.g., Fabric	Display name of the attribute on the website.	Fabric
Compare At PDP	No	Yes, No	Enables comparison on product detail page (PDP).	Yes
Compare At PLP	No	Yes, No	Enables comparison on product listing page (PLP).	Yes
Different For SerialNo	No	Yes, No	Allows unique attribute values per serial number.	Yes
Different For Variant	No	Yes, No	Allows unique attribute values per variant.	Yes
Display In Basket	No	Yes, No	Controls visibility on the basket page.	Yes
Display In ProductDetail	No	Yes, No	Controls visibility on the product detail page.	Yes
Display In ProductList	No	Yes, No	Controls visibility on the product listing page.	Yes
InputType	Yes	Dropdown, Text, MultipleSelect	Defines the input method for the attribute.	Dropdown
Use For Variant	No	Yes, No	Indicates if the attribute creates product variants.	Yes
Use In Facet Search	No	Yes, No	Determines if the attribute is used as a filter on the PLP.	Yes

Best Practices

Ensure AttributeCode is unique and consistent across related files.
Choose appropriate InputType for user interaction.
Import this file before attribute options or product mappings.

Use Cases

Defining product attributes like fabric or size.
Configuring attributes for filtering or comparison on the website.

4. Custom Attribute Option Master (CustomAttributeOptionMaster)

Overview

Defines options for custom attributes, such as values for dropdowns or multi-select fields.

Fields

Column	Required	Possible Values	Description	Example
AttributeCode	Yes	e.g., product.fabric	Matches an attribute code from Custom Attribute Master.	product.fabric
DisplayOrder	Yes	e.g., 1, 2, 3	Order in which the option appears on the website.	1
OptionText	Yes	e.g., Cotton	Display text for the attribute option.	Cotton
OptionValue	Yes	e.g., Cotton	Stored value for the attribute option (can match OptionText).	Cotton

Best Practices

Ensure AttributeCode references an existing attribute.
Use sequential DisplayOrder values for clarity.
Import after the Custom Attribute Master file.

Use Cases

Setting up dropdown options for attributes like fabric or color.
Customizing display order for attribute values.

5. Attribute Set Sample File (AttributeSetSampleFile)

Overview

Organizes attributes into sets and groups for assignment to products.

Fields

Column	Required	Possible Values	Description	Example
AttributeCode	Yes	e.g., product.fabric	Code of the attribute in the set.	product.fabric
DisplayOrder	Yes	e.g., 1	Position of the attribute within the set.	1
GroupName	Yes	Mandatory, Optional	Group within the attribute set (e.g., Mandatory, Optional).	Mandatory
SetName	Yes	e.g., Clothing	Name of the attribute set, often matching a top-level category.	Clothing

Best Practices

Ensure AttributeCode matches an existing attribute.
Use consistent GroupName values for organization.
Import after Custom Attribute Master.

Use Cases

Grouping attributes for specific product categories.
Assigning structured attribute sets to products.

6. Product Upload (ProductUploadSampleFile)

Overview

Uploads product details, including pricing, stock, and category assignments.

Fields

Column	Required	Possible Values	Description	Example
AttributeSet	No		Attribute set assigned to the product.
BarCode	No		Barcode for inventory tracking.
Brand	Yes	e.g., Brand1	Name of the brand manufacturing the product.	Davidoff
BrandId	No		Unique identifier for the brand.
Category	Yes	e.g., Studs	Category to which the product belongs.	Studs
CategoryId	No	N/A	Unique identifier for the category (not required).	N/A
ColorHex	No		Hexadecimal color code (can be ignored).
ColorText	No		Textual color representation (can be ignored).
CostPrice	Yes	e.g., 2.99	Cost to procure the product.	2.99
Currency	Yes	e.g., USD	Currency for prices (e.g., USD, EUR).	USD
CurrentStock	Yes	e.g., 145	Current stock quantity.	145
Gender	No	Men, Women, Unisex	Intended gender for the product.	Men
GTN	No		Global Trade Number for international trade.
Height	No		Product height (can be ignored).
Image1 to Image10	No	e.g., zincwasher1.jpg	Filenames for up to 10 product images.	zincwasher1.jpg
IsActive	Yes	0, 1	Indicates if product is active (1) or inactive (0).	1
ItemType	Yes	1	Item type (always 1 for initial upload).	1
Length	No		Product length (can be ignored).
Listprice	Yes	e.g., 22	Maximum retail price (RRP).	22
LongDescription	No	e.g., Yellow steel coated fasteners	Detailed product description.	Yellow steel coated fasteners
MPN	No		Manufacturer Part Number.
ParentCategory	No	e.g., Fastener	Parent category for hierarchical structure.	Fastener
ParentSKU	No	N/A	Not required (ignore).	N/A
ProductCode	No	e.g., TRHT	Parent code for the stock code.	TRHT
ProductName	Yes	e.g., Yellow steel coated fasteners	Product title displayed to customers.	Yellow steel coated fasteners
Publish	Yes	0, 1	Indicates if product is visible on storefront (1 = visible).	1
SellPrice	Yes	e.g., 19	Selling price on the website.	19
ShortDescription	No	e.g., Yellow steel coated fasteners	Brief product description.	Yellow steel coated fasteners
Size	No	e.g., small	Product size (can be ignored).	small
StockCode	Yes	e.g., TRHT003RTHY78	Unique product identifier.	TRHT003RTHY78
SubBrandId	No		Unique identifier for the sub-brand.
SubBrandName	No	e.g., Davidoff Coolwater	Name of the sub-brand.	Davidoff Coolwater
TaxClass	No	e.g., Default Tax class	Tax class for the product.	Default Tax class
UOM	No		Unit of Measure for the product.
Weight	No	e.g., 5	Product weight in kilograms.	5
Width	No		Product width (can be ignored).

Best Practices

Ensure StockCode is unique and Currency uses valid codes.
Provide image filenames with extensions for Image1 to Image10.
Import categories before products to avoid linkage errors.
Verify import status in All Activity → Imports.

Use Cases

Uploading new products with pricing and stock details.
Updating existing product information or stock levels.

7. Category Product Mapping (CategoryProductMapping)

Overview

Maps products to categories, defining their hierarchical relationships.

Fields

Column	Required	Possible Values	Description	Example
Action	Yes	Add, Delete	Action to perform for the category mapping (add or delete).	Add
CategoryCode	Yes		Specific category to which the product belongs.
ParentCategoryCode	Yes		Unique identifier for the parent category.
ProductCode	Yes	e.g., XY0211	Unique identifier for the product being mapped.	XY0211

Best Practices

Ensure CategoryCode and ParentCategoryCode reference existing categories.
Verify ProductCode matches an existing product.
Check import logs for mapping errors.

Use Cases

Assigning products to specific categories.
Updating category hierarchies for product navigation.

8. Product Attribute Set Upload (Product_AttributesSetUploadSampleFile)

Overview

Assigns attribute sets to products for structured data management.

Fields

Column	Required	Possible Values	Description	Example
Name	Yes	e.g., Shirts	Name of the attribute set assigned to the product.	Shirts
ProductCode	Yes	e.g., XY0211	Unique identifier for the product.	XY0211

Best Practices

Ensure Name matches an existing attribute set.
Verify ProductCode references an existing product.
Import after Attribute Set Sample File.

Use Cases

Assigning attribute sets to new or existing products.
Organizing product attributes for consistency.

9. Product Attribute Mapping (ProductAttributeMapping)

Overview

Maps custom attributes to products or stock codes.

Fields

Column	Required	Possible Values	Description	Example
AttributeCode	Yes	e.g., product.fabric	Code for the custom attribute.	product.fabric
AttributeValue	Yes	e.g., Cotton	Value for the specified attribute.	Cotton
Color	No		Color attribute value (can be uploaded in variant file).
Operation	Yes	Add, Delete	Action to perform for the attribute (add or delete).	Add
ProductCode	No	e.g., XY0211	Unique identifier for the product (for product-level attributes).	XY0211
StockCode	Yes	e.g., XY0211-SILVER-M	Unique identifier for the stock code (for stock-level attributes).	XY0211-SILVER-M

Best Practices

Ensure AttributeCode matches an existing attribute.
Provide either ProductCode or StockCode based on attribute level.
Import after Custom Attribute Master.

Use Cases

Assigning specific attribute values to products or stock codes.
Updating or removing attribute mappings.

10. Variants Upload (VariantsUploadSample)

Overview

Defines product variants based on attributes like color or size.

Fields

Column	Required	Possible Values	Description	Example
Attribute1	Yes	e.g., global.colour	First attribute code for the variant (e.g., color).	global.colour
Attribute1Value	Yes	e.g., #C0C0C0	Value for Attribute1 (e.g., hex code).	#C0C0C0
Attribute2	No	e.g., clothing.size	Second attribute code for the variant (e.g., size).	clothing.size
Attribute2Value	No	e.g., Small	Value for Attribute2 (e.g., size value).	Small
Attribute3	No		Additional attribute code (if applicable).
Attribute3Value	No		Value for Attribute3 (if applicable).
ProductCode	No	e.g., XY0211	Unique identifier for the base product.	XY0211
StockCode	Yes	e.g., XY0211-SILVER-M	Unique identifier for the variant stock code.	XY0211-SILVER-M
VariantGroupCode	No	e.g., XY0211-SILVER	Identifier for the variant group (auto-generated if blank).	XY0211-SILVER

Best Practices

Ensure StockCode is unique and ProductCode references an existing product.
Import after Product Upload and Custom Attribute Master.
Verify variant attributes match defined attribute codes.

Use Cases

Creating variants for products with multiple colors or sizes.
Managing stock codes for variant-specific inventory.

11. Product Image Upload (ProductImageUploadSampleFile)

Overview

Manages images for products or variants.

Fields

Column	Required	Possible Values	Description	Example
Action	Yes	Add, Delete	Action to perform for the image (add or delete).	Add
Active	Yes	0, 1	Indicates if the image is active (1) or inactive (0).	1
DisplayOrder	Yes		Order in which the image appears (lower numbers appear first).
ImageName	Yes	e.g., product_image.jpg	Filename of the image, including extension.	product_image.jpg
ProductCode	No	e.g., XY0211	Unique identifier for the product.	XY0211
StockCode	Yes	e.g., XY0211-SILVER-M	Unique identifier for the stock item.	XY0211-SILVER-M
Tag	No	e.g., front view	Label or tag for the image.	front view
VariantGroupCode	No	e.g., XY0211-SILVER	Identifier for the variant group.	XY0211-SILVER

Best Practices

Use valid image filenames with extensions.
Ensure StockCode references an existing stock item.
Monitor import logs for file format errors.

Use Cases

Adding product images for website display.
Managing variant-specific images.

12. Product Video Upload (ProductVideoUploadSampleFile)

Overview

Manages videos for products or variants.

Fields

Column	Required	Possible Values	Description	Example
Action	Yes	Add, Delete	Action to perform for the video (add or delete).	Add
Description	No		Textual description of the video content.
DisplayOrder	Yes		Order in which the video appears (lower numbers appear first).
ProductCode	No	e.g., XY0211	Unique identifier for the product.	XY0211
StockCode	Yes	e.g., XY0211-SILVER-M	Unique identifier for the stock item.	XY0211-SILVER-M
VariantGroupCode	No	e.g., XY0211-SILVER	Identifier for the variant group.	XY0211-SILVER
VideoURL	Yes		URL of the video to be uploaded.

Best Practices

Provide valid VideoURL for video content.
Ensure StockCode references an existing stock item.
Import after Product Upload.

Use Cases

Adding product videos for enhanced customer experience.
Managing variant-specific video content.

Overview

Defines related products for cross-selling on product detail pages.

Fields

Column	Required	Possible Values	Description	Example
ChildStockId	Yes		Stock ID of the related product to display.
DisplayOrder	Yes		Order in which the related product appears on the PDP.
Label	Yes		Custom text label for the related product.
MasterStockId	Yes		Stock ID of the main product on whose PDP the related product appears.
RelationshipType	Yes	e.g., ALSO LIKE, ALSO NEED	Type of relationship (e.g., ALSO LIKE, ALSO NEED).	ALSO LIKE

Best Practices

Ensure ChildStockId and MasterStockId reference existing stock items.
Use meaningful RelationshipType values for clarity.
Verify import status in All Activity → Imports.

Use Cases

Setting up cross-selling products on PDPs.
Managing related product displays for marketing.

14. Pricelist Upload (Pricelist)

Overview

Manages pricing details for products, including retail and wholesale prices.

Fields

Column	Required	Possible Values	Description	Example
Color	No		Color name for display on the PDP.
LandedCost	Yes	e.g., 4.32	Total cost to acquire and bring the product to inventory.	4.32
Pricelist	Yes	e.g., Default Pricelist	Name of the pricelist configured in PIM.	Default Pricelist
ProductCode	Yes	e.g., XY0211	Unique identifier for the product (common for variants).	XY0211
RRP	Yes	e.g., 13	Suggested retail price for the product.	13
RRPExcVat	No	e.g., 10.4	Retail price excluding VAT.	10.4
SalePriceExcVat	Yes	e.g., 9.59	Selling price excluding taxes.	9.59
StockCode	Yes	e.g., XY0211-SILVER-M	Unique identifier for the product or bundle.	XY0211-SILVER-M
WSalePrice	Yes	e.g., 11.99	Price at which the product is sold to customers.	11.99

Best Practices

Ensure Pricelist matches a configured pricelist in PIM.
Verify ProductCode and StockCode reference existing items.
Import after Product Upload.

Use Cases

Setting up pricing for products or variants.
Updating retail and wholesale prices.

General Best Practices

File Format: Use CSV format with headers matching field names exactly.
Data Validation:
- Populate all compulsory fields.
- Ensure unique identifiers (e.g., CategoryCode, StockCode) are consistent across files.
- Validate numerical (e.g., CostPrice) and boolean (e.g., Active) fields.
Import Order:
- Import categories before products.
- Import attributes before attribute sets and product mappings.
Monitoring:
- Check All Activity → Imports for status (Success, Error, Processing).
- Download imported files from logs for auditing.
Error Handling:
- Review error logs for issues like duplicate identifiers or missing fields.
- Correct and re-upload files as needed.

Use Cases

Onboarding new products with categories, attributes, and pricing.
Updating product images, videos, or variant details.
Managing category hierarchies and product mappings for navigation.
Setting up cross-selling or pricing strategies.

Support

For issues with imports or troubleshooting failed jobs:

Team: DataOps & Integrations
Email: pim-support@yourcompany.com
Last Updated: June 5, 2025

✅ Summary

The Imports functionality in the PIM system enables seamless management of product catalog data through structured CSV files. By following the field requirements and best practices for each file type, teams can efficiently upload and update categories, products, attributes, and related data. Monitor import statuses via All Activity logs to ensure data integrity and resolve issues promptly, maintaining a robust and synchronized product catalog.