Most retailers should submit their inventory to VersaFeed utilizing the source feed format detailed below. Retailers requiring API integration can jump to the API notes below.
Important Notes
- Existing file: If you have an existing feed file, please notify VersaFeed (we can very likely utilize the existing format)! This can be a tremendous time saver for merchants.
- Format: Submit source feeds as TSV (tab separated value) files (we may be able to accept other formats as well).
- Modifications: Please note that once we process your feed, you should not change the format of your feed. Modifying the feed may result in additional charges for VersaFeed engineers to re-map, modify, and Q/A the new format.
- Encoding: Please encode the feed in UTF-8. If you use another encoding, please notify VersaFeed.
- Submission: Inventory can either be pushed to VersaFeed or pulled by VersaFeed using HTTP(S) or (S)FTP.
- Sample template: Download a sample XLS template file for your reference. *Please note, the file must be saved as "text (tab-delimited)" before submission to VersaFeed.
Field Specifications
Required Fields:
- id: A product's unique ID. Should not change over time and should be unique from all other items, including variations. It is safest to use some sort of internal SKU if available. Avoid using UPC or MPN unless you are sure that the code is truly unique and will not change.
- name: The title of the product. Should typically be 55 or less characters. Anything beyond 70 characters will be truncated. More information on product titles is available here.
- description: The detailed product description. Do not use promotional phrases such as "25% off" or "free shipping". Usually 2-4 sentences describing the product are sufficient.
- price: The current price of the product in USD. If you have sale prices, you must include these prices as a separate field OR adjust this field (price) to reflect the sale price.
- url: The URL link to the product.
- category: Internal product category (e.g., "Shoes > Reebok", "Electronics : Computers : Laptops").
- image_url: The URL to the primary image for this product. Utilize high resolution if available, and always a minimum of 400x400 pixels. It is also recommended to utilize a white background. Images cannot be generic in any fashion, they must be an actual picture of the item. Images cannot contain watermarks.
- availability: If your feed only contains in-stock items, this is not needed. If your feed contains both in-stock and out-of-stock items, you will need to provide this information in the feed.
- brand: Specify the brand of the product (more info here). If all of your items are one brand or there are a limited number of brands in your product catalog, this field can sometimes be ignored.
Highly Recommended Fields:
- gtin: Specify the GTIN of the product (more info here). Google requires GTIN if the product has a manufacturer-defined GTIN.
- mpn: Specify the MPN (Manufacturer Part Number) of the product (more info here)
- condition: If you only sell new items this field is not needed. If you sell used or refurbished items, this field is required.
Recommended:
- google_product_category: If available, provide the most relevant category from the Google taxonomy here. If not available, VersaFeed can create this for you.
- image_url[2-10]: Specify additional images by utilizing this attribute (i.e., image_url2, image_url3, image_url4, etc.).
- weight: Specify the weight of the product. Please include unit of measurement (e.g., 10lb, 5 pounds, 1.3kg, etc.)
- shipping: Specify the shipping cost of item. Setting to 0 or 0.00 indicates free shipping. If you have well established shipping costs, you may be able to omit this field. Contact a VersaFeed account manager for more information.
Variations:
Many products will have multiple variations. For apparel retailers, this information is highly recommended. Variant products in the TSV file only need specify attributes that are different than the parent product (although retailers can duplicate information on each row if desired).
- group_id: Group ID, set all items that are variants of the same product to the same group_id. The group_id can be any alphanumeric code; its only job is to group similar items together.
- size: Specify the size of the item in whatever format is most suitable for your products (e.g., XL, 10"x20", small, petite, etc.)
- color: Specify the color of the item
- age_group: Specify either "Adult" or "Kids"
- gender: Specify either "Male", "Female", or "Unisex".
- material: Specify the material (e.g., denim, leather, lycra, etc.)
- pattern: Specify the pattern (e.g., striped, polka-dot, paisley, etc.)
Custom Attributes:
VersaFeed recommends including additional product information even if it does not correlate to an attribute described below. Do this by adding columns prefixed with "c:". For example, a "memory" attribute could be titled "c:memory" and the column might have data such as "8GB", "16GB", etc.
Advanced (Optional):
- Cost of Goods: Provide cost of goods per product for advanced Google reporting metric possibilities
- Quantity on Hand: Provide actual numeric quantity of products available.
- Department / Alternative Category: If multiple categories are available please provide for additional reporting/bidding options.
- Promotional Details: Include details like percent off, buy-one-get-one, or other discounts (and promotion timeframes) where available.
Download source feed template
Download a sample XLS template file for your reference. *Please note, the file must be saved as "text (tab-delimited)" before submission to VersaFeed.
If your ecommerce team would prefer that VersaFeed use your API to pull in product information, that is OK too. Note that this can result in additional fees as VersaFeed software engineers will need to write code to interact with your API.
Provide API Documentation:
Please provide your VersaFeed onboarding rep with all of your API documentation. This must include information on your various API endpoints and data structures passed at those endpoints. Examples of the kind of documentation VersaFeed is looking for are noted below:
Note: if your API documentation is not complete or inaccurate, VersaFeed may not be able to onboard your store using your API.
Additional API Requirements
- Your API should make available all of the product attributes noted above for standard source feeds. E.g., all of the areas detailed above under "Field Specification" (id, name, description, price, URL, etc.) should be provided by your API in some fashion.
- Provide details on your API authentication scheme (e.g., OAuth, shared secret key with hashing, etc.).
- Provide details on any methods to facilitate request batching for bulk API requests.
- Provide any execution frequency limits. E.g., if you don't allow more than X requests per second/minute please document this.
- Provide example code fragments in at least one popular language. E.g., an API login and product "get" request in a language like Java, Python, JavaScript, or PHP.