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
Required
Description
Example

id

String

Yes

Unique product identifier

"12345"

handle

String

Yes

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.

"summer-tshirt"

title

String

Yes

Product title/name

"Envive T-Shirt"

description

String

Yes

Product description

"This is a sample product description"

link

String

Yes

Direct link to product page

"https://example.com/products/summer-tshirt"

image_link

URL

Yes

Primary product image URL

"https://example.com/images/sample.jpg"

availability

"in_stock", "out_of_stock", "preorder", "backorder"

Yes

Product availability status

"in_stock"

price

String

Yes

Product price with currency

"19.99 USD"

sale_price

String

No

Sale price with currency

"15.99 USD"

brand

String

Yes

Product brand name

"Envive"

gtin

String

No

Global Trade Item Number

"1234567890123"

mpn

String

No

Manufacturer Part Number

"MPN123"

condition

"new", "refurbished", "used"

No

Product condition, default "new"

"new"

age_group

"newborn", "infant", "toddler", "kids", "adult"

No

Target age group

"adult"

item_group_id

String

No

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.

"group123"

google_product_category

String (kebab-case, comma-separated)

Yes

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.

"summer-collection,new-arrivals,mens-clothing"

tags

String (kebab-case, comma-separated)

No

Product tags for enhanced filtering and categorization. Useful for search refinement and product discovery. (kebab-case as a convention)

"organic-cotton,eco-friendly,best-seller"

product_review_id

String

No

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.

"12345" or "group123"

bundle_products

String (comma-separated)

No

List of component product handles that make up a bundle product. Use the product handles (from the `handle` column) for the bundled items.

"summer-tshirt,ceramic-mug,classic-cap"

additional_image_links

String (comma-separated URLs)

No

Additional product image URLs

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

custom_label_0

String

No

Custom label field

"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.

PreviousEnvive Data APINextAnalytics

Last updated