Bulk product upload

Bulk upload lets you manage hundreds of products without editing them one by one. It is ideal for price updates, stock adjustments, or adding new products.

• Generate a CSV template pre-loaded with your current catalog.
• Edit existing products in bulk.
• Create new products by leaving product_id empty.
• Update images from an external URL.
• Update exchange rates in bulk for the currency_exchange vertical.

1. Go to Inventory > Products (/items).
2. Click the three-dot menu (⋮) at the top.
3. Select Bulk product upload.

The template is a CSV with all your current products already loaded. If this is your first time, you need to generate it.

1. If no template exists yet, click Generate template and wait.
2. If a template is ready, the main button shows Download template.
3. Download the CSV and open it in Excel, Google Sheets, or any spreadsheet editor.

Before editing the template, keep these rules in mind to avoid import errors.

• Do not delete or rename column headers.
• For existing products, keep the product_id.
• For new products, leave product_id empty and set a unique import_key.
• If a product appears in multiple rows (one per location), shared fields must be consistent across all rows.
• To clear a shared field, clear it in all rows for the same product.

The inventory_tracking_mode field defines how product stock is tracked.

• quantity: tracks stock by count. Use inventory_quantity to set available units.
• availability: no count tracking. Use inventory_is_available (true/false) to mark whether the item is available.

1. Download the template.
2. Filter the rows for the product or products you want to update.
3. Edit price, inventory_tracking_mode, inventory_quantity, and inventory_is_available as needed.
4. Save the file and upload it in Step 2.

import_key,product_id,inventory_scope,location_id,item_type,name,price,inventory_tracking_mode,inventory_quantity,inventory_is_available
3c9...,3c9...,location,6d2...,physical,Black t-shirt,79900,quantity,12,true

1. Duplicate a reference row or add a new one at the end of the CSV.
2. Leave product_id empty.
3. Set a unique import_key for the new product.
4. Fill in at least name and item_type.
5. Optionally add price, image_url, and inventory fields.
6. Upload the CSV.

import_key,product_id,inventory_scope,location_id,item_type,name,description,price,image_url,inventory_tracking_mode,inventory_quantity,inventory_is_available
new-coffee-01,,all,,prepared_food,Origin Coffee,Medium roast,18000,https://example.com/coffee.jpg,availability,,true

If your vertical is currency_exchange, the template includes columns for managing exchange rates. You can edit margins or set prices directly.

1. Download the FX template.
2. Edit fx_buy_margin_percent, fx_sell_margin_percent, or the direct prices fx_buy_price and fx_sell_price.
3. If you have a rates API configured, set fx_auto_pricing to true to let the system recalculate automatically.
4. Upload the CSV.

import_key,product_id,item_type,name,fx_base_currency,fx_quote_currency,fx_reference_code,fx_quote_unit,fx_auto_pricing,fx_buy_margin_percent,fx_sell_margin_percent
usd-cop,8f1...,foreign_exchange_asset,US Dollar,USD,COP,USD,1,true,1.5,2.1

1. In the bulk upload modal, go to Step 2.
2. Select and upload the edited CSV.
3. Wait for the background run to complete.
4. Review the results summary and any errors.

You can update a product's image using the image_url column.

• If the URL has not changed from the current value, no re-sync occurs.
• If the URL changes, the system downloads the image and uploads it to internal storage.
• The image is automatically linked to the product.

• Existing products are identified by product_id. Do not change that value.
• You cannot overwrite stock for products with variant-level inventory.
• location_name is for visual reference only; the location is resolved by location_id.
• Processing is asynchronous; always review the final summary.
• Validate critical changes in a test organization before running them at full scale.