CSV Ingestion

CSV file structure for catalog ingestion

To guarantee the successful ingestion of your catalog, please adhere to the file requirements specified below.

This CSV format is based on Google Merchant Center Product Data Specification, with additional fields required for Envive's product retrieval and review collection.

CSV Header Row

id,product_review_id,handle,title,description,link,image_link,availability,price,sale_price,brand,gtin,mpn,condition,age_group,item_group_id,google_product_category,tags,bundle_products,additional_image_links,custom_label_0

CSV Schema

Field Name	Supported Values	Description	Required	Example
id	String	Unique product identifier	Yes	"12345"
handle	String	Product slug/handle used in your store's URL structure. For a product at shop.com/products/summer-tshirt, the handle is "summer-tshirt". This is critical for product page retrieval and matching user events to products.	Yes	"summer-tshirt"
title	String	Product title/name	Yes	"Envive T-Shirt"
description	String	Product description	Yes	"This is a sample product description"
link	String	Direct link to product page	Yes	"https://example.com/products/summer-tshirt"
image_link	URL	Primary product image URL	Yes	"https://example.com/images/sample.jpg"
availability	"in_stock", "out_of_stock", "preorder", "backorder"	Product availability status	Yes	"in_stock"
price	String	Product price with currency	Yes	"19.99 USD"
sale_price	String	Sale price with currency	No	"15.99 USD"
brand	String	Product brand name	Yes	"Envive"
gtin	String	Global Trade Item Number	No	"1234567890123"
mpn	String	Manufacturer Part Number	No	"MPN123"
condition	"new", "refurbished", "used"	Product condition, default "new"	No	"new"
age_group	"newborn", "infant", "toddler", "kids", "adult"	Target age group	No	"adult"
item_group_id	String	Group identifier for product variants (e.g., different sizes/colors of the same product). Use this to group variants that share the same base product.	No	"group123"
google_product_category	String (kebab-case, comma-separated)	Collections/categories for Product Listing Page (PLP) retrieval. When users browse shop.com/collections/summer-collection, Envive uses this field to identify relevant products. Provide as a comma-separated list of collection handles/IDs (should be in kebab-case) that match your store's URL structure.	Yes	"summer-collection,new-arrivals,mens-clothing"
tags	String (kebab-case, comma-separated)	Product tags for enhanced filtering and categorization. Useful for search refinement and product discovery. (kebab-case as a convention)	No	"organic-cotton,eco-friendly,best-seller"
product_review_id	String	Identifier used for review collection. This should match the ID used in your review system to link reviews to products. Please note, you must include this field if you wish Envive to utilize your reviews in any way. Envive recommends that you exclude this field ONLY if you do not have reviews for a given product.	No	"12345" or "group123"
bundle_products	String (comma-separated)	List of component product handles that make up a bundle product. Use the product handles (from the `handle` column) for the bundled items.	No	"summer-tshirt,ceramic-mug,classic-cap"
additional_image_links	String (comma-separated URLs)	Additional product image URLs	No	"https://example.com/images/img1.jpg,https://example.com/images/img2.jpg"
custom_label_0	String	Custom label field	No	"custom_value"

Key Field Explanations

Product Review ID (product_review_id)

The product_review_id field specifies which identifier Envive should use when collecting and associating reviews with products. This field provides flexibility for different review architectures.

Why this matters: Without this dedicated field, Envive cannot reliably determine which ID to use for review collection, especially when merchants have both id and item_group_id columns with different values.

Product Handle (handle)

This is the most critical field for product retrieval. It must match the slug/handle used in your product URLs.

Example URL patterns:

• Shopify: https://yourstore.com/products/summer-tshirt → handle: summer-tshirt

• Custom store: https://shop.com/p/organic-cotton-tee → handle: organic-cotton-tee

Envive uses this field to match user events (page views, clicks) to specific products in your catalog. When a user visits a product page, the handle is extracted from the URL and used to retrieve the correct product data.

Important: The handle must exactly match what appears in your URLs. If your URL uses dashes, underscores, or specific casing, replicate that exactly in this field.

Collections/Categories (google_product_category)

This field enables Product Listing Page (PLP) retrieval and is essential for collection-based recommendations.

How it works: When a user visits https://yourstore.com/collections/summer-collection, Envive identifies all products with summer-collection in their google_product_category field.

Best practices:

• Include all relevant collections/categories as a comma-separated list

• Use the exact collection handles from your URLs (should be in kebab-case)

• Example: "summer-collection,new-arrivals,mens-clothing,sale-items"

Why this matters: PLPs are critical touchpoints in the shopping journey. This field allows Envive to:

• Provide contextual recommendations based on the collection being browsed

• Show relevant products when users explore specific categories

• Enable collection-specific analytics and personalization

Tags (tags)

While optional, tags significantly improve product filtering and discovery. They provide additional metadata that can be used for search refinement and recommendation logic.

Example use cases:

• Product attributes: "organic,cotton,breathable,moisture-wicking"

• Marketing features: "bestseller,editor-pick,limited-edition,new-arrival"

• Seasonal markers: "spring-2024,holiday-gift,summer-sale"

• Use cases: "casual-wear,office-appropriate,athletic,formal"

Format: Comma-separated list of tag values, using the same handles/slugs that appear in your filter URLs if applicable (should be in kebab-case)

Additional Images (additional_image_links)

Provide multiple additional product images as a comma-separated list of fully qualified URLs.

Example: "https://example.com/images/img1.jpg,https://example.com/images/img2.jpg,https://example.com/images/img3.jpg"

Notes:

• image_link is the primary image; these are secondary.

• Use consistent aspect ratios across images.

• Avoid tracking parameters when possible.

Product variants using item_group_id

Use one row per product variant and use item_group_id to reference the parent product it belongs to using parent product's handle, not its id. A product variant row should keep its own handle empty. If your reviews are product-level, keep product_review_id empty, otherwise fill in the product_review_id if the reviews are at the variant-level. The parent product row with child variants should not have an item_group_id.

Example:

Assuming product 7714809151699 is the parent product and the rest are variants belonging to the parent product.

id	handle	title	price	availability	item_group_id	image_link	product_review_id
7714809151699	summer-tee	Envive Summer Tee				https://example.com/images/summer-tee-s.jpg	summer-tee-review-id
0109274812331		Envive Summer Tee - Small	19.99 USD	in_stock	summer-tee	https://example.com/images/summer-tee-m.jpg
1231140094759		Envive Summer Tee - Large	19.99 USD	out_of_stock	summer-tee	https://example.com/images/summer-tee-l.jpg

id,handle,title,price,availability,item_group_id,image_link,product_review_id
7714809151699,summer-tee,Envive Summer Tee,,,,,https://example.com/images/summer-tee-s.jpg,summer-tee-review-id
0109274812331,,Envive Summer Tee - Small,19.99 USD,in_stock,summer-tee,https://example.com/images/summer-tee-m.jpg,
1231140094759,,Envive Summer Tee - Large,19.99 USD,out_of_stock,summer-tee,https://example.com/images/summer-tee-l.jpg,

Notes:

• item_group_id groups variants; no separate parent row is required.

• For variant-level reviews, set product_review_id to each row’s id instead.

• Other fields (e.g., gtin, mpn, additional_image_links) can be variant-specific when needed.

Bundles (bundle_products)

Defines bundles generically via CSV. If a row represents a bundle product, list the component product handles in bundle_products as a comma-separated list.

Rules:

• Use the product handles (from the handle column) for the component products

• Provide handles as a comma-separated list

• Order does not matter

• Components must also exist as separate rows in the CSV

Examples:

• Bundle row id=gift-set-001 with bundle_products="summer-tshirt,ceramic-mug,classic-cap"

• Bundle row id=winter-pack with bundle_products="wool-beanie,thermal-gloves,scarf-plaid"

Important: Always use the product handles in the comma-separated list, not the product IDs. The handles ensure proper product matching and retrieval within Envive's system.

This maps to platform-specific implementations (e.g., Shopify metafield bundle_products) while keeping the CSV portable.