Skip to main content

Upload Data Import

POST 
/api/v2/data-imports

Uploads mapped CSV data for import and kicks off background validation. Returns the data import ID and a tracked job log ID to poll for validation progress.

Not yet available to API tokens

This endpoint currently requires session authentication; Personal Access Token scope support is in progress.

Authentication: Requires Bearer token.

Per-entity authorization: For the gated entity types the user must hold the matching permission: customers, warehouses, suppliers, sales_reps, categories, incoterms, duty-rates and currencies need <entity>.import (e.g. customers.import); planning_policies and mps_entries need mrp.run; boms, recipes, bom_outputs and bom_operations need manufacturing.import; fba_stock_floors (FBA minimum stock levels) needs fba_stock_floors.update. Other entity types are not gated here.

FBA minimums import (entity_type fba_stock_floors): upserts FBA minimum stock levels by (Amazon account, region, product). Fields: product_sku (required; blank = the region default), amazon_account (account name; optional when the tenant has one Amazon account), region (required; country code or EU), floor_mode (units | days | greater_of), min_units, min_days_of_cover, route_type (supplier | own_warehouse | third_party_warehouse | awd), route_source (supplier or warehouse name), include_inbound, ignore_inbound_after_days, alerts_enabled. Blank cells leave a setting unset (inherit). The Export FBA Minimums endpoint produces a file in this shape. The check resolves through the granular_permissions feature flag — it is a no-op while that flag is off. Returns 403 when the user lacks the required permission.

Request Body:

  • entity_type (required, string): Type of entity being imported (e.g. products, customers, warehouses, suppliers, sales_reps, fba_stock_floors)
  • file_name (required, string, max:255): Original filename for display
  • column_mapping (required, array): Maps column positions to field names
  • mapped_rows (required, array, min:1): Array of row objects with mapped field values
  • metadata (nullable, array): Optional metadata

entity_type must be a registered import type (see List Import Entities); an unknown type is a 422. Some types also need the permission their own screen requires: warehouse_transfers and warehouse_transfer_lines need warehouse_transfers.import; products and supplier_links need products.import; rmas needs returns.create; amazon_fnsku_initial_costs and veracore_product_mappings need integrations.update. Without it the upload returns 403.

Also gated: sales_credit_lines needs returns.update, vendor_credit_lines needs purchase_orders.update and product_listing_inventory needs listings. Landed cost bills: billsneedspurchase_orders.create; bill_allocationsandbill_paymentsneedpurchase_orders.update`.

Landed cost bill imports: bills (one row per bill line; rows sharing id or invoice_number form one bill, an existing bill is updated and a new invoice number created; fields id, invoice_number, invoice_date, supplier_name, supplier_email, link_type, link_reference, currency_code, currency_rate, payment_term, proration_strategy, line_description, line_quantity, line_amount, line_cost_category, line_tax_rate, line_nominal_code — a bill with any error is rejected whole), bill_allocations (manual allocations of existing bills, one row per document line: id or invoice_number, allocation_sku or allocation_line_id, allocation_amount; the rows replace that bill's allocations and make it manual) and bill_payments (one row per payment: id or invoice_number, payment_date, amount, payment_method, reference; the same bill + payment method + reference updates that payment, and payments may not exceed the bill's remaining balance).update(the same permission as each screen's own import route). Contact imports take their owner's import permission frommetadata.link_type (supplier→suppliers.import, customer→customers.import, warehouse→warehouses.import); a missing or unknown link_type` is a 422 "A valid owner (link_type) is required for contact imports."

Request​

Responses​

Created