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:
- Upload: open Catalog → Products → Import, configure options, and upload your CSV or ZIP. Socialone immediately validates all rows.
- 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. - 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_confirmationstatus and can be found in Import Jobs. - 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_urlandadditional_images. - ZIP with images: bundle your image files and a CSV named
products.csvinto 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
- 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. - 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.
- Name the CSV file
products.csv. If the ZIP contains multiple CSV files, the first one found is used. - In the CSV, set
image_urlto the bare filename (not a path) — e.g.tshirt-black-front.jpg, notimages/tshirt-black-front.jpg. - For additional gallery images, set
additional_imagesto a comma-separated list of filenames — e.g.tshirt-black-back.jpg,tshirt-black-detail.jpg. - 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
| Requirement | Detail |
|---|---|
| Formats | JPG, JPEG, PNG, GIF, WebP, AVIF |
| Max file size | 8 MB per image. Larger images are skipped — the product row still imports but with no image. |
| Max images per product | 1 primary (image_url) + up to 20 additional (additional_images) |
| Recommended dimensions | Minimum 500 × 500 px. Square (1:1) recommended for WhatsApp catalog. Meta requires at least 500 × 500 px for catalog approval. |
| Background | White or light background recommended for WhatsApp and Meta catalog display. |
| Filename uniqueness | Each 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
skucolumn to match existing products. - Set
image_urlto the new filename or URL. This replaces the current primary image. - Set
additional_imagesto 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, andadditional_imagescolumns — 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(orretailer_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:
| Type | Use when | Example |
|---|---|---|
| Standard (per-variant stock) | Each option has its own independent stock counter and price | T-shirt in S/M/L and Black/White |
| Shared-pool (commodity) | All pack sizes draw from one physical stock total. Price = base_price × pack size | Rice sold as 500g, 1kg, 5kg bags from the same 100 kg sack |
Standard variant group — step by step
Four rules to remember:
- Every row in the group gets the same
item_group_id— pick any string that is unique to this group (e.g.TEE-CLASSIC). - Put the option axis labels (
option1_name,option2_name) on the first row only. Leave them blank for all other rows. - Every row gets its own unique
sku. - 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:
inventory_scope = shared— tells the importer this is a shared-pool group.inventory_unit— the physical unit the pool is counted in:kg,g,litre,ml,each, ordozen.base_price— your price per one unit of the pool (e.g. ₹120 per kg). Leave thepricecolumn blank for all rows — it is calculated.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_idvalues across rows — they will be created as separate products, not variants of the same group. - Setting
priceon shared-pool rows — the value is ignored. Usebase_priceon the template row instead. - Putting
option1_nameon 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_factoron 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
| Column | Required | What it does |
|---|---|---|
| name | Yes | Product display name. Max 500 characters. |
| sku / retailer_id | No | Your 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. |
| description | No | Plain-text product description shown on the web store and in product messages. |
| rich_text_description | No | HTML-formatted description used by Meta's rich_text_description field. Supports basic tags. Leave blank if you do not need HTML formatting. |
| brand | No | Brand or manufacturer name. Required by Meta for some catalog categories. |
| gtin | No | Global Trade Item Number — UPC, EAN, ISBN, or GTIN-14. Used for Meta catalog compliance. |
| mpn | No | Manufacturer Part Number. Used for Meta catalog compliance. |
| product_url | No | URL to the product's page on an external website. Used by Meta for catalog linking. |
| tags | No | Comma-separated tags (e.g. 'summer,sale,cotton'). Searchable in the product list. |
Pricing
| Column | What it does |
|---|---|
| price | Regular selling price. Required unless base_price is set (shared-pool groups). Must be ≥ 0. |
| compare_at_price | Original / crossed-out price shown alongside the sale price. Displays as a strikethrough on the web store. |
| sale_price | Time-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. |
| currency | ISO currency code. Defaults to INR when not specified. |
| cost_price | Purchase 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_slabs | Tiered / 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_price | Template-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
| Column | What it does |
|---|---|
| availability | Stock status. Valid values: in_stock, out_of_stock, preorder, discontinued. Invalid values default to in_stock. |
| stock_quantity | Starting 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_active | Whether 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_quantity | Minimum number of units a customer must order. Leave blank for no minimum. |
| product_type | physical, digital, service, or subscription. Affects shipping, checkout, and delivery method defaults. Invalid values default to physical. |
| condition | new, refurbished, or used. Used by Meta catalog. Invalid values default to new. |
| requires_shipping | Whether 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
| Column | What it does |
|---|---|
| shipping_weight | Shipping 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_unit | Unit for the shipping_weight value: kg, g, lb, or oz. Only needed when shipping_weight is a bare number. |
| tax_rate | GST rate percentage: 0, 5, 12, 18, or 28. Null = tax exempt. Set in the product form; not currently importable via CSV. |
| hsn_code | HSN 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.
| Column | What it does |
|---|---|
| image_url | Primary 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_images | Gallery 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.
| Column | What it does |
|---|---|
| item_group_id | Groups 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_name | Display 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_name | Label 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_name | Label for the second variant axis — e.g. 'Weight', 'Colour'. Optional. |
| option3_name | Label for the third variant axis. Optional. |
| option1 | This variant's value for option1_name. E.g. if option1_name is 'Cut', option1 might be 'Slim' or 'Regular'. |
| option2 | This variant's value for option2_name. |
| option3 | This variant's value for option3_name. |
| color | Classic color attribute. Automatically synced from option1/2/3 when the matching option axis is named 'color'. |
| size | Classic size attribute. Synced similarly from named option axes. |
| material | Material attribute (cotton, linen, etc.). |
| pattern | Pattern attribute (stripes, solid, floral, etc.). |
| gender | male, female, or unisex. Used for Meta catalog targeting. |
| age_group | adult, teen, kids, toddler, infant, or newborn. Used for Meta catalog targeting. |
| inventory_scope | Template-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_unit | Template-level unit for the shared pool: each, kg, g, litre, ml, or dozen. Only relevant when inventory_scope=shared. |
| uom_factor | Per-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.
| Column | Valid values | What it does |
|---|---|---|
| web_visibility | inherit | published | hidden | Whether the product appears on the web store. inherit = use store default. |
| commercial_mode | inherit | checkout | booking | enquiry | catalogue | How the product behaves on the web store. checkout = add to cart; booking = book a slot; enquiry = enquiry form; catalogue = display only, no action. |
| price_display | inherit | exact | from | on_request | hidden | How the price is shown. from = show lowest variant price; on_request = hide price; hidden = no price shown. |
Compliance & Meta Catalog
| Column | What it does |
|---|---|
| google_product_category | Google product taxonomy ID or name. Used by Meta catalog for category mapping. |
| fb_product_category | Meta/Facebook product category. Used for catalog compliance and ad targeting. |
| origin_country | Country where the product was manufactured. Required by Meta when wa_compliance_category is DEFAULT (most physical goods sold in India). |
| wa_compliance_category | COUNTRY_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_4 | Five 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_stockwith 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_idandbase_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_priceon each row and Update existing if SKU matches enabled. The importer updates the template from the first row'sbase_price. - Explicit override per variant: set an explicit
priceon 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 usingbase_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_slabsto blank clears all tiers and falls back to the standard price. - The base
pricecolumn 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:
- Review the error list to understand why each row failed.
- Create a new CSV with only the failed rows, corrected.
- 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 →