CSV Import: Products

The format and the fields description of a products.csv file.

Seller Labs avatar
Written by Seller Labs
Updated over a week ago

This article applies to the specific versions of software: X-Cart 5.3.3 and later


File Format

A product CSV file for import must have the name products-xxxxxx.csv, where the part -xxxxxx can be anything you want or even be omitted.

Examples of correct product CSV file names:

  • products.csv;

  • products-13-01-01.csv;

  • products-from-my-provider.csv

A product CSV file must contain at least two fields:

  1. sku - unique identifier of the product;

  2. name - product name.

Example of the simplest product CSV file:

Fields Reference

There are many more fields that you can include in your product CSV file. Below we provided a list of supported fields and value types accepted by X-Cart via these fields.

Fields supported by X-Cart core

CSV file field name

What this field describes

sku*

Unique identifier of the product.

String,
Max. length: 32

name*

Product name.

String,
Multilingual

price

Default product price.

Float (e.g., 1.00)

memberships

Membership types, which members can see the product. Do not set it if you want to make the product visible to all customers. Otherwise, it will be visible to the users assigned to specified membership only.

String,
Multiple

description

Full description of the product.

String,
Multilingual,
HTML allowed

briefDescription

Brief description of the product that is shown on the catalog pages.

String,
Multilingual,
HTML allowed

enabled

Whether the product is enabled.

Yes/No

weight

Product weight.

Float (e.g., 8.00)

shippable

Whether the product can be shipped physically

Yes/No

images

For any image that needs to be imported, you need to specify the image location. This can be one of the following:

  • Image URL (can be local to the X-Cart server);

  • Path to the image on the server relative to the <XCART-DIRECTORY> folder; for example, images/product/image1.png.

Note that if you require to store images for import inside the "images" folder of your X-Cart store installation, they must be placed inside the folder "images/product" or a subfolder of "images/product"; X-Cart will not be able to import images stored in the folder "images" outside the subfolder "images/product." It will be able, however, to import images stored in other locations within your <XCART-DIRECTORY> folder, outside of the folder "images."

Correct:

  • images/product/test.jpg

  • images/product/test/test.jpg

  • images1/test.jpg

Incorrect:

  • images/test.jpg

  • images/test/test.jpg

Also, note that the images import takes considerably less time if the images to be imported are stored locally on the server. It does not matter if the image path is specified as a URL or as a file path — X-Cart will try to detect if the URL is local to the server. So, if you need to import a considerable number of images stored elsewhere, you can speed up the process quite a bit simply by saving those images locally on the server inside the folder <XCART-DIRECTORY>/images/product.


It is possible to specify more than one image for import by separating the image paths with the && symbols;

for example, images/product/image1.png&&images/product/images2.png.

String,
Multiple

imagesAlt

Text for alt property of images. This text will be shown when an image is not loaded for some reason.

If many images are assigned to the product, you can import many alt texts as well. These alt texts must be separated by && construction.

Examples:

  • Alt text for the first image (1 alt-text)

  • Alt text for first image&&Alt text for second image (2 alt texts)

String,
Multiple,
Max. length: 255

arrivalDate

Date when the product will be available for sale.

Date (e.g., 1 Jan 2022)

date

Date when of the product creation in the X-Cart Admin area.

Date (e.g., 1 Jan 2022)

updateDate

The date of the last product update.

Date (e.g., 1 Jan 2022)

inventoryTrackingEnabled

Whether inventory (stock) tracking is enabled.

Yes/No

stockLevel

Current stock level.

Integer

lowLimitLevel

When the stock of the product reaches this amount, the admin will get a notification about the low limit of these goods.

Integer (e.g. 10)

lowLimitEnabled

Whether low stock notification is enabled

Yes/No

minimumPurchaseQuantity

The minimum allowed quantity for purchase.

If the store administrator adds the field, it must be imported along with the vendor field. The vendor field value should be either empty if the product owner is the store admin or a vendor email if the product owner is a vendor.

If the minimumPurchaseQuantity field is imported by a vendor, no additional fields are required.

Integer

categories

The categories to which the product belongs.

Separate the category names by the >>> construction for nested categories.

Multiple categories can be specified, separated by the && construction.

Examples:

  • Toys (product resides in the root category "Toys")

  • Toys>>>Cube Goodies (product resides in the category "Toys/Cube Goodies")

  • Toys&&Toys>>>Cube Goodies (products resides in two categories: "Toys" and "Toys/Cube Goodies")

String,
Multiple

inCategoriesPosition

Determines the position of the product within a category relative to the other products in the same category.

If the product belongs to multiple categories, specify the product position in each of them using the xx&&yy&&zz format.

Integer (xx/yy/zz)

cleanURL

SEO-friendly URL of the product page.

Example: apple.html

Clean URLs are imported according to the following rules:

  1. If the cleanURL field doesn't exist in a .csv file, the product Clean URL field stays unchanged.

  2. If the cleanURL field value is defined in a CSV file and this field is empty for a product at the moment of import, the respective product property is created the product Clean URL gaining the value of the respective field from the CSV file.

  3. If the cleanURL field value is defined in a CSV file and this field is NOT empty (exists) for a product at the moment of import, the respective product Clean URL value is substituted with the one from the CSV file if the field value doesn't conflict with any of the existing Clean URLs values. If the conflict exists, the cleanURL field value is automatically modified by adding -1 to the end of the field value.

String

useSeparateBox

Whether a separate box needs to be used for this item when you ship it

Yes/No

boxWidth

If useSeparateBox is Yes, this field defines the width of the custom box for this product

Float (e.g., 1.00)

boxLength

If useSeparateBox is Yes, this field defines the length of the custom box for this product

Float (e.g., 1.00)

boxHeight

If useSeparateBox is Yes, this field defines the height of the custom box for this product

Float (e.g., 1.00)

itemsPerBox

If useSeparateBox is Yes, this field defines what quantity of the product can be shipped in this box.

Integer (e.g., 3)

metaTags

Defines the content of <meta name="keywords" content="%value%"> meta tag

String,
Multilingual,
Max. length: 255

metaDesc

Defines the content of <meta name="description" content="%value%"> meta tag

String,
Multilingual

metaDescType

Defines meta description content type. Can be either A or C, where:

  • "A" stands for automatic mode when meta description will be generated from product description;

  • "C" stands for custom mode when meta description will be taken from metaDesc_* field in an appropriate translation*;
    *this means that if the store uses the English language, the meta description will be taken from metaDesc_en field.

String,
Max. length: 1

metaTitle

Defines the content of <meta name="title" content="%value%"> meta tag

String,
Multilingual,
Max. length: 255

productClass

Defines attribute class for a product.

See also:

String

[attribute_name](field:product)

Defines a product-specific attribute for the product, where [attribute_name] stands for the name of the product-specific attribute

e.g. Color(field:product)

String,
Multilingual,
Max. length: 255

taxClass

Defines the tax class for the product

String

Fields added by the Go Social add-on

CSV file field name

What this field describes

useCustomOpenGraphMeta

Defines whether use custom Open Graph meta tags for this product or use default ones

Yes/No

openGraphMeta

If useCustomOpenGraphMeta is Yes, then defines custom Open Graph meta tags

String,
HTML allowed,
Scripting allowed


Fields added by the File Attachments add-on

CSV file field name

What this field describes

attachments

Defines what files are attached to this product.

For any file that needs to be imported, you need to specify the file location. This can be one of the following:

  • File URL

  • Path to the file on the server.

If using the latter option (local filepath), the attachment files for import need to be placed in one of the following locations:

  • The folder <XCART-DIRECTORY>/files/attachments, or its subfolders. The path in the CSV file, in this case, must be specified relatively to <XCART-DIRECTORY>; for example, files/attachments/user-manual.pdf or files/attachments/test/user-manual.pdf

  • The folder <XCART-DIRECTORY>/var/import, or its subfolders. The path in the CSV file, in this case, must be specified relatively to <XCART-DIRECTORY>; for example, var/import/user-manual.pdf or var/import/test/user-manual.pdf. Note that files placed in the folder <XCART-DIRECTORY>/var/import will be copied as a result of import to the folder <XCART-DIRECTORY>/files/attachments/[product_id].

Multiple files can be attached, and they must be separated by the && construction.

Examples:

  • path/to/my/files/user-manual.pdf (1 file)

  • path/to/my/files/user-manual.pdf&&path/to/my/files/spec.pdf (2 files)

Note that import of attachments takes considerably less time if the files to be imported are stored locally on the store server rather than elsewhere. Therefore, if you need to import a considerable number of attachment files stored away from the store server, it may be possible to speed up the process simply by saving those files locally on the server and changing the location of those files in the import CSV file accordingly.

String,
Multiple

attachmentsTitle

Defines the titles of attachment files.

This field supports titles for many attachments, and they must be separated by && construction.

Examples:

  • User manual (title of 1 attachment)

  • User manual&&Tech spec (title of 2 attachments)

String,
Multiple,
Multilingual,
Max. length: 128

attachmentsDescription

Defines the description of the attachments file.

This field supports descriptions for many attachments, and they must be separated by && construction.

Examples:

  • This is a user manual for the product (description for 1 attachment)

  • This is a user manual for the product&&This is a tech spec for the product (description for 2 attachments)

String,
Multiple,
Multilingual

Fields added by the E-Goods add-on

CSV file field name

What this field describes

attachmentsPrivate

Defines what attachments should be private and available after an order has been paid for (e-goods) and what attachments should be available right from the product page (the Product Attachments and E-Goods add-ons must be enabled).

In the case of multiple attachments, it is possible to mark some of them as private and some as publicly available. Multiple values must be separated by the && construction.

Example:

  • Yes (the product has one attachment, and it is private)

  • Yes&&No (the product has two attachments, the first one is private and the second one is public)

Fields added by the Market Price add-on

CSV file field name

What this field describes

marketPrice

Defines the product's market price so your customers can estimate how much less than the average price of the product on the market they will need to pay if they buy the product from you.

Float (e.g., 5.00)

Fields added by the Sale add-on

CSV file field name

What this field describes

sale

Defines your discount for this product.

It can have two types of values (absolute discount and percent one):

  • 10.00 means that this product will receive a $10 discount, assuming that the dollar is your store currency.

  • %10 means that this product will receive a 10% discount

String

saleDiscounts

Defines a global discount assigned to a product. See how to configure global discounts here.

Multiple discount offers can be specified, separated by the && construction.
e.g., Sale_1&&Sale_2

String

Fields added by the Multi-Vendor add-on

CSV file field name

What this field describes

vendor*

Product vendor login name

String

Fields added by the Product Variants add-on

CSV file field name

What this field describes

(X-Cart 5.3.3+) variantID

Autogenerated product variant identifier

String,
Autogenerated,
Multirow

variantSKU

Product variant SKU (if empty, takes SKU from parent product)

String,
Max. length: 32,
Multirow

variantPrice

Product variant price (if empty, takes price from parent product)

Float,
Multirow

variantQuantity

Product variant quantity (if empty, takes quantity from parent product)

Integer,
Multirow

variantWeight

Product variant weight (if empty, takes weight from parent product)

Float,
Multirow

variantImage

Product variant image location

String,
Multirow

variantImageAlt

Product variant image alt text

String,
Max. length: 32,
Multirow

Fields added by the Variants Table View add-on

CSV file field name

What this field describes

variantsAsTable

Display product variants in the Table mode.

Yes/No

Fields added by the Wholesale add-on

CSV file field name

What this field describes

wholesalePrices

Defines wholesale prices for the product.

Examples:

  1. You want to set up price tiers as follows:
    If a customer buys from 1 to 5 items, each item will cost $50
    If they buy from 6 items, then the price will be $45

    Then you would need to specify this system as follows in the CSV file:
    1-5=50.00&&6=45.00

  2. You want to set up price tiers as follows:
    If a customer buys from 1 to 5 items, each item will cost $50
    If they buy from 6 items, then the price will be $45
    If a customer with a Wholesaler membership buys from 3 items, then the price will be $40

    Then you would need to specify this system as follows in the CSV file: 1-5=50.00&&6=45.00&&3(Wholesaler)=40.00

String,
Multiple

variantWholesalePrices

Defines wholesale prices for the product variant.

The add-on Product Variants must be enabled.

String,
Multiple,
Multirow

Fields added by the UPC/ISBN and Mnf#/Vendor# fields add-on

CSV file field name

What this field describes

upcIsbn

UPC/ISBN code

String,
Max. length: 32

mnfVendor

Manufacturer of the product

String,
Max. length: 64

variantupcIsbn

Product variant UPC/ISBN code.

The add-on Product Variants must be enabled.

String,
Max. length: 32,
Multirow

variantmnfVendor

Manufacturer of the product variant.

The add-on Product Variants must be enabled.

String,
Max. length: 64,
Multirow

Fields added by the Related Products add-on

CSV file field name

What this field describes

relatedProducts

SKUs of related products. You can specify several products, separating them with && symbols.

Examples:

  • SKU1 (1 product)

  • SKU1&&SKU2 (2 products)

String,
Multiple

Fields added by the Make/Model/Year add-on

CSV file field name

What this field describes

fitmentType

The fitment type of the product.

Possible values are:

  • regular;

  • universal;

  • specific.

String

Fields added by the Product Tags add-on

CSV file field name

What this field describes

tags

Product tags values

Multiple values must be separated by && construction.

String,
Multiple

Fields added by the Free Shipping and Shipping Freights add-on

CSV file field name

What this field describes

shipForFree

Enables/disables the "Free shipping" option for a product

Yes/No

freeShipping

Enables/disables the "Exclude from shipping cost calculation" option for a product

Yes/No

freightFixedFee

Defines a fixed shipping fee for a product

Float (e.g., 1.00)

Fields added by the Product Feeds add-on

CSV file field name

What this field describes

nextagId

Adds a NexTag feed category to a product

NexTag Category ID

shopzillaId

Adds a Shopzilla feed category to a product

Shopzilla Category ID

pricegrabberId

Adds a Pricegrabber feed category to a product

Pricegrabber Category ID

ebayCommerceId

Adds an eBay Commerce Network (shopping.com) feed category to a product

eBay Category ID

googleShoppingId

Adds a Google Shopping feed category to a product

Google Shopping Category ID

Fields added by the Request for Price & Hide Prices add-on

CSV file field name

What this field describes

callForPrice

Enables the "Call for price" option for a product

Yes/No

variantCallForPrice

Enables the "Call for price" option for a product variant

Yes/No

Fields added by the Backorder/Preorder add-on

CSV file field name

What this field describes

availableForBackorder

Enables the "Available for backorder" option for the product

Yes/No

backorderQtyLabel

Defines a backorder promo text that is displayed to customers when a product is out of stock

It's possible to insert the number of units available for backordering by using the %number% placeholder.

EXAMPLE: You can back-order up to %number% items.

String

Multilingual

HTML allowed

isBackorderLimited

Enables the "Limit the backorder quantity" option for the product.

Yes/No

backorderLimit

Defines the maximum backorder quantity.

Integer

* Required field.

** See CSV Field Notices for more info.

Tips:

  • If you are going to import data into X-Cart and do not wish to update certain X-Cart fields during the import process, you should not include these fields in your CSV file for import. Instead, simply remove the respective column(s) from the file.

  • If necessary, you can use import to clear previously set field values from non-numeric fields. To clear a field value via import, in your CSV file to be imported, specify the field's value as "NULL." Then import this file into your store.

    The following product fields support this feature:

    • memberships;

    • categories;

    • images;

    • imagesAlt;

    • attributeValue;

    • variantImage (Product Variants addon).

    Important: importing "NULL" in the field images will not only cancel the image assignment to the product but will result in the physical removal of the image from the server.

Related pages:

Did this answer your question?