Socialone Logo

Bulk Import Products

Bulk import creates or updates many products from a single CSV or ZIP file. The importer validates the entire file first and shows you a preview — how many will be created, updated, or skipped, and any errors — before processing begins.

New to products?

Bulk import is for large-scale creation and updates. For creating or editing a single product, see Create & Edit Products. For variants and shared-pool inventory, see Product Variants. For syncing to WhatsApp and Meta, see Product Meta Sync.

Staged Workflow

Every import follows this two-step process:

  1. Upload: open Catalog → Products → Import, configure options, and upload your CSV or ZIP. Socialone immediately validates all rows.
  2. Review the manifest: the system shows will_create, will_update, will_skip, validation errors, and any warnings. No products have been created or changed yet.
  3. Confirm: click Confirm Import to start processing. Only confirmed imports write to the database. If you close the modal without confirming, the import stays in awaiting_confirmation status and can be found in Import Jobs.
  4. Processing: runs in the background. Progress is shown in real time. You can close the modal and return later.

Validation window

The manifest is valid for 30 minutes. If you wait longer before confirming, Socialone will warn you that the preview may be stale — product data may have changed since validation. Review the results carefully.

File Formats

  • CSV only: images must be hosted online already — use full HTTPS URLs in image_url and additional_images.
  • ZIP with images: bundle your image files and a CSV named products.csv into a single ZIP. The importer uploads each image to Socialone and replaces the filename in the CSV with the hosted URL. See Adding Images via ZIP below.
  • Encoding: save the CSV as UTF-8. UTF-8 BOM is accepted. Quotes around fields that contain commas are required.

Adding Images via ZIP

When your product images are stored locally (not yet online), bundle them with the CSV inside a ZIP archive. Socialone uploads every image, then stores the hosted URLs on the product records automatically.

How to prepare the ZIP

  1. Name your image files clearly — e.g. tshirt-black-front.jpg, tshirt-black-back.jpg. Filenames must be unique across the entire ZIP; duplicates cause one to be silently ignored.
  2. Put all images and your CSV in a single folder and compress it to a ZIP. The folder structure inside the ZIP does not matter — the importer scans all subfolders and matches images by filename only.
  3. Name the CSV file products.csv. If the ZIP contains multiple CSV files, the first one found is used.
  4. In the CSV, set image_url to the bare filename (not a path) — e.g. tshirt-black-front.jpg, not images/tshirt-black-front.jpg.
  5. For additional gallery images, set additional_images to a comma-separated list of filenames — e.g. tshirt-black-back.jpg,tshirt-black-detail.jpg.
  6. Upload the ZIP via Catalog → Products → Import.

Example ZIP structure and CSV

my-products.zip
├── products.csv
├── tshirt-black-front.jpg
├── tshirt-black-back.jpg
└── tshirt-white-front.jpg

products.csv:
name,sku,price,image_url,additional_images
Classic Tee Black,TEE-BLK,599,tshirt-black-front.jpg,tshirt-black-back.jpg
Classic Tee White,TEE-WHT,599,tshirt-white-front.jpg,

Image requirements

RequirementDetail
FormatsJPG, JPEG, PNG, GIF, WebP, AVIF
Max file size8 MB per image. Larger images are skipped — the product row still imports but with no image.
Max images per product1 primary (image_url) + up to 20 additional (additional_images)
Recommended dimensionsMinimum 500 × 500 px. Square (1:1) recommended for WhatsApp catalog. Meta requires at least 500 × 500 px for catalog approval.
BackgroundWhite or light background recommended for WhatsApp and Meta catalog display.
Filename uniquenessEach filename must be unique within the ZIP. Duplicate filenames cause one to be ignored silently.

Updating images on existing products

To replace images on products that already exist:

  • Include the sku column to match existing products.
  • Set image_url to the new filename or URL. This replaces the current primary image.
  • Set additional_images to the full new list of gallery images. This replaces the entire gallery — it does not append. Leave blank to clear all gallery images.
  • Enable Update existing if SKU matches in import options before uploading.
  • If you only need to update images and nothing else, include only sku, image_url, and additional_images columns — absent columns leave other product data unchanged.

Using hosted URLs instead of a ZIP

If your images are already hosted (Cloudinary, Google Drive public links, your own CDN, etc.), skip the ZIP entirely. Put the full URL directly in image_url and additional_images in the CSV. The importer downloads and re-hosts each image on Socialone automatically.

Google Drive links need adjustment

Standard Google Drive share links (drive.google.com/file/d/…/view) do not work as direct image URLs. Use the direct download format: https://drive.google.com/uc?export=download&id=FILE_ID. The file must be shared publicly.

Import Options

  • Update existing products if SKU matches: when enabled, rows whose sku (or retailer_id) matches an existing product update that product rather than create a duplicate. Only columns present in the CSV header are updated — absent columns leave the DB value unchanged. Rows without a SKU always create new products even with this toggle on.
  • Assign to catalogs: select one or more catalogs to assign all successfully imported products to. Existing catalog assignments are preserved — this adds to them, not replaces.

Web Policy Batch Mode

The Web Policy Batch Mode lets you set the web store behavior for all imported products at once, without adding web_visibility, commercial_mode, and price_display columns to every row:

  • Keep existing behavior (default): do not change any product's web policy. Use this for price or stock updates where you do not want to touch web store settings.
  • Apply to new rows only: apply the chosen bulk policy to newly created products only. Existing products are not changed.
  • Apply to all rows: apply the bulk policy to both new and updated products. Existing policies are overwritten.

Per-row web_visibility / commercial_mode / price_display columns in the CSV take precedence over the batch mode setting.

Importing Variant Groups

A variant group is a product sold in multiple options — different sizes, colours, pack sizes, or any combination. Each option combination is its own row in the CSV but they are all linked under one product listing by a shared item_group_id.

There are two types of variant groups. Choose the one that matches your product:

TypeUse whenExample
Standard (per-variant stock)Each option has its own independent stock counter and priceT-shirt in S/M/L and Black/White
Shared-pool (commodity)All pack sizes draw from one physical stock total. Price = base_price × pack sizeRice sold as 500g, 1kg, 5kg bags from the same 100 kg sack

Standard variant group — step by step

Four rules to remember:

  1. Every row in the group gets the same item_group_id — pick any string that is unique to this group (e.g. TEE-CLASSIC).
  2. Put the option axis labels (option1_name, option2_name) on the first row only. Leave them blank for all other rows.
  3. Every row gets its own unique sku.
  4. Every row gets its own price. Use the same price if all options cost the same.

Example — T-shirt, 3 sizes × 2 colours (6 variants)

name,sku,price,item_group_id,template_name,option1_name,option2_name,option1,option2,stock_quantity
Classic Tee S Black,TEE-S-BLK,599,TEE-CLASSIC,Classic Tee,Size,Colour,S,Black,20
Classic Tee M Black,TEE-M-BLK,599,TEE-CLASSIC,,,,M,Black,20
Classic Tee L Black,TEE-L-BLK,599,TEE-CLASSIC,,,,L,Black,20
Classic Tee S White,TEE-S-WHT,599,TEE-CLASSIC,,,,S,White,20
Classic Tee M White,TEE-M-WHT,599,TEE-CLASSIC,,,,M,White,20
Classic Tee L White,TEE-L-WHT,599,TEE-CLASSIC,,,,L,White,20

Only row 1 needs template_name and the option axis labels. All other rows leave them blank — the importer reads the template from row 1 and applies it to the whole group. Each row creates one independent product with its own SKU and stock counter.

Result: 6 products in Socialone, grouped under the "Classic Tee" listing. Customers see one product page with Size and Colour dropdowns. Each variant tracks its own stock independently.

Shared-pool (commodity) group — step by step

Use this when your physical stock is one pool and you sell it in different pack sizes. All pack sizes draw from the same counter. Price is not set per variant — it is calculated as base_price × uom_factor.

Four things to set on the first row only:

  1. inventory_scope = shared — tells the importer this is a shared-pool group.
  2. inventory_unit — the physical unit the pool is counted in: kg, g, litre, ml, each, or dozen.
  3. base_price — your price per one unit of the pool (e.g. ₹120 per kg). Leave the price column blank for all rows — it is calculated.
  4. stock_quantity — the total pool quantity on hand (e.g. 100 for 100 kg).

On every row, set uom_factor to how much of the pool one unit of that variant consumes:

Example — Basmati Rice in 4 pack sizes (pool = kg)

name,sku,item_group_id,template_name,option1_name,option1,inventory_scope,inventory_unit,base_price,uom_factor,stock_quantity
Basmati Rice 500g,RICE-500G,RICE-BAS,Basmati Rice,Pack Size,500g,shared,kg,120,0.5,100
Basmati Rice 1kg,RICE-1KG,RICE-BAS,,,1kg,,,,,
Basmati Rice 2kg,RICE-2KG,RICE-BAS,,,2kg,,,,,
Basmati Rice 5kg,RICE-5KG,RICE-BAS,,,5kg,,,,,

Add uom_factor values on rows 2–4 (1.0, 2.0, 5.0 — omitted above for readability). Only the first row needs inventory_scope, inventory_unit, base_price, and stock_quantity.

Result: 4 products linked to a 100 kg pool. Prices auto-calculate — 500g = ₹60, 1kg = ₹120, 2kg = ₹240, 5kg = ₹600. Selling one 5 kg bag deducts 5 kg from the shared pool automatically.

Common variant import mistakes

  • Different item_group_id values across rows — they will be created as separate products, not variants of the same group.
  • Setting price on shared-pool rows — the value is ignored. Use base_price on the template row instead.
  • Putting option1_name on every row instead of just the first — the importer reads it from the first row and ignores duplicates, but it bloats the file unnecessarily.
  • Missing uom_factor on shared-pool rows — the importer defaults to 1.0, so a 500g bag would price the same as a 1kg bag.

After importing your variants

  • Advanced Inventory — set minimum order quantities (MOQ), slab pricing, and unit-of-measure rules per variant or for the whole group.
  • Inventory Management — view on-hand levels, available-to-sell (ATS) stock, and reorder thresholds across locations.
  • Product Variants — deeper reading: inventory scope decisions, WhatsApp catalog behavior, web store policy per variant.

Full Column Reference

Download the CSV template from the import modal to get the correct column headers. Only name and price are required. All other columns are optional — columns absent from the header are ignored on updates.

Core Identity

ColumnRequiredWhat it does
nameYesProduct display name. Max 500 characters.
sku / retailer_idNoYour internal SKU. Used as the match key for upserts and by Meta as retailer_id. Auto-generated as a random ID when not provided. Cannot be changed after creation.
descriptionNoPlain-text product description shown on the web store and in product messages.
rich_text_descriptionNoHTML-formatted description used by Meta's rich_text_description field. Supports basic tags. Leave blank if you do not need HTML formatting.
brandNoBrand or manufacturer name. Required by Meta for some catalog categories.
gtinNoGlobal Trade Item Number — UPC, EAN, ISBN, or GTIN-14. Used for Meta catalog compliance.
mpnNoManufacturer Part Number. Used for Meta catalog compliance.
product_urlNoURL to the product's page on an external website. Used by Meta for catalog linking.
tagsNoComma-separated tags (e.g. 'summer,sale,cotton'). Searchable in the product list.

Pricing

ColumnWhat it does
priceRegular selling price. Required unless base_price is set (shared-pool groups). Must be ≥ 0.
compare_at_priceOriginal / crossed-out price shown alongside the sale price. Displays as a strikethrough on the web store.
sale_priceTime-limited promotional price. Shown to customers instead of price when active. Set the active window via sale_price_effective_date in the product form after import.
currencyISO currency code. Defaults to INR when not specified.
cost_pricePurchase or landed cost per unit (not visible to customers). Used for gross margin and COGS calculations in analytics. Set in the product form; not currently importable.
price_slabsTiered / volume pricing. Format: 'min_qty:price,min_qty:price' — e.g. '10:299.00,50:249.00'. When set, customers buying ≥10 units pay ₹299, ≥50 pay ₹249. Blank clears all slabs.
base_priceTemplate-level price per inventory unit for shared-pool (commodity) product groups. When set on a template, each variant's effective price = base_price × uom_factor. Variant-level price cells should be blank when using base_price.

Availability & Stock

ColumnWhat it does
availabilityStock status. Valid values: in_stock, out_of_stock, preorder, discontinued. Invalid values default to in_stock.
stock_quantityStarting on-hand quantity as a whole number. Blank = unlimited / not tracked. For multi-location organisations, this initialises the inventory item at the import job's default location.
is_activeWhether the product is active (visible in the product list and eligible for catalog sync). Values: true / 1 / yes to activate, false / 0 / no to deactivate. Blank = leave unchanged.
min_order_quantityMinimum number of units a customer must order. Leave blank for no minimum.
product_typephysical, digital, service, or subscription. Affects shipping, checkout, and delivery method defaults. Invalid values default to physical.
conditionnew, refurbished, or used. Used by Meta catalog. Invalid values default to new.
requires_shippingWhether the product needs a delivery address. Defaults to true. Set to false / 0 / no for digital products that should not trigger address collection.

Shipping & Tax

ColumnWhat it does
shipping_weightShipping weight used for live courier quotes. Accepts two formats: a bare number (use with shipping_weight_unit column), or a combined string like '0.5 kg' or '300 g'.
shipping_weight_unitUnit for the shipping_weight value: kg, g, lb, or oz. Only needed when shipping_weight is a bare number.
tax_rateGST rate percentage: 0, 5, 12, 18, or 28. Null = tax exempt. Set in the product form; not currently importable via CSV.
hsn_codeHSN or SAC code for GST invoices. Required for Indian GST compliance. Set in the product form; not currently importable.

Images

See Adding Images via ZIP above for the full image workflow, file requirements, and how to update images on existing products.

ColumnWhat it does
image_urlPrimary product image. Full HTTPS URL for hosted images, or bare filename (e.g. shirt-blue.jpg) when using a ZIP. Replaces the current primary image on update.
additional_imagesGallery images shown on the web store product page. Comma-separated full URLs or bare filenames. Up to 20. Replaces the entire gallery on update — does not append.

Variants & Template Fields

See Product Variants for a full explanation of the template system and option axes.

ColumnWhat it does
item_group_idGroups rows as variants of the same product. All rows with the same item_group_id are linked under one ProductTemplate. Used by Meta to group variants in the catalog. Must match across all variants in the group.
template_nameDisplay name for the ProductTemplate (the parent of the variant group). Only the first row for a group needs this. For new groups without this column, the first variant's name is used.
option1_nameLabel for the first custom variant axis — e.g. 'Cut', 'Flavour', 'Pack Size'. Defined once per group (use the first row). Defaults to 'size' when not set.
option2_nameLabel for the second variant axis — e.g. 'Weight', 'Colour'. Optional.
option3_nameLabel for the third variant axis. Optional.
option1This variant's value for option1_name. E.g. if option1_name is 'Cut', option1 might be 'Slim' or 'Regular'.
option2This variant's value for option2_name.
option3This variant's value for option3_name.
colorClassic color attribute. Automatically synced from option1/2/3 when the matching option axis is named 'color'.
sizeClassic size attribute. Synced similarly from named option axes.
materialMaterial attribute (cotton, linen, etc.).
patternPattern attribute (stripes, solid, floral, etc.).
gendermale, female, or unisex. Used for Meta catalog targeting.
age_groupadult, teen, kids, toddler, infant, or newborn. Used for Meta catalog targeting.
inventory_scopeTemplate-level: per_variant (each variant has its own stock counter) or shared (all variants draw from a shared pool). Set once per group. Default: per_variant.
inventory_unitTemplate-level unit for the shared pool: each, kg, g, litre, ml, or dozen. Only relevant when inventory_scope=shared.
uom_factorPer-variant: how many units from the shared pool this variant consumes per packet sold. E.g. a 350g packet with a kg-unit pool has uom_factor=0.35. Default: 1.0.

Web Store Policy

These three columns must always be set together — if any one is non-inherit, all three must be explicit. Setting only one or two causes a validation error.

ColumnValid valuesWhat it does
web_visibilityinherit | published | hiddenWhether the product appears on the web store. inherit = use store default.
commercial_modeinherit | checkout | booking | enquiry | catalogueHow the product behaves on the web store. checkout = add to cart; booking = book a slot; enquiry = enquiry form; catalogue = display only, no action.
price_displayinherit | exact | from | on_request | hiddenHow the price is shown. from = show lowest variant price; on_request = hide price; hidden = no price shown.

Compliance & Meta Catalog

ColumnWhat it does
google_product_categoryGoogle product taxonomy ID or name. Used by Meta catalog for category mapping.
fb_product_categoryMeta/Facebook product category. Used for catalog compliance and ad targeting.
origin_countryCountry where the product was manufactured. Required by Meta when wa_compliance_category is DEFAULT (most physical goods sold in India).
wa_compliance_categoryCOUNTRY_ORIGIN_EXEMPT (services and digital products that do not need origin/importer fields) or DEFAULT (physical goods — must include origin_country and importer details in OMS Settings).
custom_label_0 … custom_label_4Five free-form labels for internal segmentation or Google Shopping ad grouping (e.g. 'clearance', 'bestseller', 'margin-high'). Max 100 characters each.

Group Command Rows

A group command row is a special CSV row that changes a field for every variant in a group at once — without naming each variant individually. It has an item_group_id but no sku, name, or price.

  • Supported fields: availability, is_active, base_price, template_name.
  • The command is applied after per-variant rows are processed, so individual rows in the same import that set the same fields take precedence over the group command.
  • Use case example: set all 12 variants of a T-shirt to availability=out_of_stock with one row instead of 12.

Example group command row

item_group_id,availability,is_active
TSHIRT-BLK,,  ← this row has no sku/name/price, only item_group_id
TSHIRT-BLK,out_of_stock,0  ← sets all TSHIRT-BLK variants to out of stock and inactive

Updating Prices

How you update a product's price depends on whether it is a standard product, a per-variant group, or a shared-pool (commodity) group. Each type prices differently and needs a different update approach.

Standard and per-variant products

Each product (or variant) has its own explicit price. Download the Price Update Template from the import modal — it has four columns: sku, price, compare_at_price, sale_price.

  • One row per SKU. Leave any column blank to keep its current value.
  • For a variant group, include one row per variant SKU. Each row updates that variant independently.
  • Enable Update existing if SKU matches before uploading.
  • Only pricing columns in the file are updated — no other product data is affected.

Shared-pool (commodity) groups

Shared-pool variants do not have individual prices. Their price is computed as base_price × uom_factor, where base_price lives on the template, not the variants. Updating price per variant has no effect — you must update base_price.

  • Via group command row: create a CSV with one row containing item_group_id and base_price (no sku, name, or price columns). This updates the template's base price and all variant prices recalculate immediately.
  • Via a full re-import: include the full variant CSV with the new base_price on each row and Update existing if SKU matches enabled. The importer updates the template from the first row's base_price.
  • Explicit override per variant: set an explicit price on a specific variant row to override the formula for that size (e.g. a bulk-discount pack). All other variants without an explicit price continue using base_price × uom_factor.
# Group command row — updates base_price for the whole shared-pool group
item_group_id,base_price
RICE-GROUP,65

Tiered / slab pricing

Slab pricing is set via the price_slabs column, not the price template. Include it in a full update CSV alongside the sku column.

  • Format: min_qty:price,min_qty:price — e.g. 10:299.00,50:249.00.
  • Setting price_slabs to blank clears all tiers and falls back to the standard price.
  • The base price column still sets the tier-1 (qty 1+) price. Only include both columns if you are updating both.

SKU is permanent

Once a product is created, its SKU (retailer_id) cannot be changed through import or the product form. It is the permanent identifier used by Meta and the match key for all future upserts. Set the correct SKU on the first import.

Understanding the Manifest

  • will_create: rows that will create new products (no matching SKU found).
  • will_update: rows whose SKU matched an existing product — will update it.
  • will_skip: rows with no name or no price (and no base_price column) that cannot be processed.
  • validation_errors: rows with specific problems — invalid price, conflicting web policy, group command on a group not found in the file, etc. Errors are shown with the row number and SKU so you can fix and re-upload just those rows.
  • Warnings: non-fatal notices — missing image_url column, stale manifest (>30 min), important columns absent for new products.

Fixing Failed Rows

You do not need to re-import the entire file when only some rows fail:

  1. Review the error list to understand why each row failed.
  2. Create a new CSV with only the failed rows, corrected.
  3. Re-upload with Update existing if SKU matches enabled. Rows that already succeeded will update cleanly by SKU.

Related Docs

Related product

Commerce & Orders for WhatsApp selling

Manage WhatsApp catalogs, products, variants, bulk imports, product messages, carts, payments, and order follow-up from one Socialone workspace.

View product →