Product CSV Import Guide

This guide explains how vendors can prepare a CSV file to bulk import products into the Bingo Connect.

Overview

The product importer supports:

• Basic product details
• Product pricing
• Priced variants
• Product options and option items
• Up to 4 image URL columns (image1Url to image4Url)

Image URL columns are accepted and validated, but image download/attachment is not yet executed during CSV import.

Import endpoint

Use the products import API with multipart form data:

• POST /products/import
• Form field: categoryId (required, one of the available category IDs)
• Form field: file (CSV)

File requirements

• File extension: .csv
• Encoding: UTF-8
• First row: header row
• One product per row
• If a value contains commas, wrap it in quotes (")

Base columns

Type-specific notes

• Category is applied per upload request via categoryId, so all rows in one file are imported into the same category.
• PRICED_VARIANT: use variant prices, not base unitPrice
• DIGITAL: importer creates product record only; file media upload is handled separately

Variant columns (dynamic)

Use incremental numbered columns:

• variant_1_name
• variant_1_unitPrice
• variant_1_comparisonPrice (optional)
• variant_2_name
• variant_2_unitPrice
• ...

Variant rules

• Minimum for PRICED_VARIANT: 2 variants
• Maximum for PRICED_VARIANT: 5 variants
• Variant names must be unique per product
• Variant prices must be unique per product

Option columns (dynamic)

Options are nested by option index and item index:

• option_1_name
• option_1_item_1_name
• option_1_item_1_unitPrice
• option_1_item_1_comparisonPrice (optional)
• option_1_item_2_name
• option_1_item_2_unitPrice
• option_2_name
• ...

Option rules

• Option names must be unique per product
• Item names must be unique within each option
• Item unitPrice can be 0

Image URL columns

You can include up to four URL columns:

• image1Url
• image2Url
• image3Url
• image4Url

Rules:

• Must be absolute http or https URLs
• Invalid URLs fail the row validation
• URLs are currently validated only (not attached to product media yet)

Alternate header style

The importer also supports bracket style columns:

• variants[0].name
• variants[0].unitPrice
• options[0].name
• options[0].items[0].name
• options[0].items[0].unitPrice

For spreadsheet authoring, underscore style is recommended because it is easier to read.

Sample CSV

A ready sample file is available at:

• src/main/resources/import-templates/products-import-sample.csv

Error handling behavior

Import is row-based:

• Valid rows are created
• Invalid rows are returned with row number and error details
• Response includes totalRows, importedCount, failedCount, data, and errors

Quick tips

• Start with a small file (2-5 rows)
• Keep column names exact
• Avoid duplicate variant names/prices
• Validate URLs before upload
• Fix failed rows and re-upload