Home / Recipes / CSV Import

CSV Import

Bulk import items and orders from CSV files. Useful for initial data loading, ERP integration, and migrating from other systems.

Prerequisites

Import items

CSV format

Required columns: id, length, width, height, weight.

Optional columns: name, description, category, hscode, countryoforigin, tags, shape, shipalone, maxpercontainer, freightclass, velocityclass, casepackquantity, caselength, casewidth, caseheight, caseweight.

Example CSV:

id,name,length,width,height,weight,category,tags,shape
WIDGET-LG-001,Large Widget,12,8,6,2.5,widgets,fragile;electronics,rectangular
GADGET-SM-042,Small Gadget,4,4,3,0.8,gadgets,,rectangular
MONITOR-27IN,27-inch Monitor,28,18,8,12.0,electronics,fragile,rectangular
KEYBOARD-MECH,Mechanical Keyboard,17,6,2,2.1,peripherals,,rectangular
MOUSE-ERGO,Ergonomic Mouse,5,3,2,0.3,peripherals,,rectangular
CABLE-USB-C,USB-C Cable 6ft,6,4,1,0.1,cables,,rectangular

Column notes:

Upload

curl -X POST https://api.fractalpack.com/api/v1/items/import/csv \
  -H "X-Api-Key: fpk_test_your_api_key" \
  -F "file=@items.csv"

Response

{
  "created": 4,
  "updated": 2,
  "errors": []
}

Items are upserted: if an item with the same id already exists, it is updated. New items are created.

With case pack data

Include case pack columns for items that ship in cases:

id,name,length,width,height,weight,casepackquantity,caselength,casewidth,caseheight,caseweight
BOLT-M8,M8 Bolt,0.5,0.25,1.5,0.02,100,8,6,10,3.0
WASHER-M8,M8 Washer,0.3,0.3,0.05,0.005,500,6,6,4,3.5

Import orders

CSV format

Required columns: sku (or itemid), quantity.

Optional columns: orderid, sourcesystem, sourceorderid, ordertype, priority, servicelevel, channel, requiredshipby, requireddeliverby, tags, description, unitofmeasure, length, width, height, weight, specialinstructions, lotnumber, customername, customerid, customeraccount, shiptoname, shiptostreet1, shiptocity, shiptostate, shiptozip, shiptocountry, shiptoresidential, shipfromname, shipfromstreet1, shipfromcity, shipfromstate, shipfromzip, shipfromcountry.

Each row is an order line. Rows with the same orderid column are grouped into a single order. If orderid is not present, all rows become lines on one order.

Example CSV:

orderid,sku,quantity,length,width,height,weight,shiptoname,shiptostreet1,shiptocity,shiptostate,shiptozip,shiptocountry,customername
ORD-001,WIDGET-LG-001,3,12,8,6,2.5,Jane Smith,456 Oak Ave,New York,NY,10001,US,Jane Smith
ORD-001,GADGET-SM-042,2,4,4,3,0.8,Jane Smith,456 Oak Ave,New York,NY,10001,US,Jane Smith
ORD-002,MONITOR-27IN,1,28,18,8,12.0,Acme Corp,100 Business Pkwy,Chicago,IL,60601,US,Acme Corp
ORD-002,KEYBOARD-MECH,1,17,6,2,2.1,Acme Corp,100 Business Pkwy,Chicago,IL,60601,US,Acme Corp
ORD-002,MOUSE-ERGO,2,5,3,2,0.3,Acme Corp,100 Business Pkwy,Chicago,IL,60601,US,Acme Corp
ORD-003,CABLE-USB-C,10,6,4,1,0.1,Bob Jones,789 Pine St,Austin,TX,73301,US,Bob Jones

Column notes:

Using itemId references

If items exist in the Item Master, use itemid instead of inline dimensions:

orderid,itemid,sku,quantity,shiptoname,shiptostreet1,shiptocity,shiptostate,shiptozip,shiptocountry
ORD-004,WIDGET-LG-001,WIDGET-LG-001,5,Jane Smith,456 Oak Ave,New York,NY,10001,US
ORD-004,GADGET-SM-042,GADGET-SM-042,3,Jane Smith,456 Oak Ave,New York,NY,10001,US

When itemid is provided without inline dimensions, the dimensions are resolved at shipment creation time.

Upload

curl -X POST https://api.fractalpack.com/api/v1/orders/import/csv \
  -H "X-Api-Key: fpk_test_your_api_key" \
  -F "file=@orders.csv"

Response

{
  "ordersCreated": 2,
  "ordersUpdated": 1,
  "ordersUnchanged": 0,
  "totalLines": 6,
  "errors": []
}

Orders are upserted by sourceOrderId. If an order with the same source ID exists, its lines are updated.

Handling partial failures

Some rows may fail validation while others succeed:

{
  "ordersCreated": 2,
  "ordersUpdated": 0,
  "ordersUnchanged": 0,
  "totalLines": 4,
  "errors": [
    {
      "row": 5,
      "orderId": "ORD-003",
      "error": "Row 5: quantity is required and must be > 0"
    },
    {
      "row": 7,
      "orderId": "ORD-004",
      "error": "Row 7: width is required when itemId is not provided."
    }
  ]
}

For item imports, errors include the row number and item ID:

{
  "created": 8,
  "updated": 0,
  "errors": [
    {
      "index": 4,
      "itemId": "BAD-ITEM",
      "error": "Row 4: length must be > 0"
    },
    {
      "index": 9,
      "itemId": "",
      "error": "Row 9: id is required"
    }
  ]
}

Partial failures are expected. Rows that pass validation are imported; failed rows are reported in the errors array. Fix the failures and re-upload only the corrected rows.

CSV formatting rules

Constraints

Constraint Items Orders
File size 5 MB 5 MB
Max rows 10,000 10,000
Required columns id, length, width, height, weight sku or itemid, quantity
Auth requirement Admin role Any authenticated user
Content type multipart/form-data multipart/form-data

Error handling

Status Cause Fix
400 No file uploaded Send as multipart form data with a file
400 Empty CSV (no data rows) Add data rows after the header
400 Missing required column Check that all required columns are present in the header
403 Not admin (items only) Item CSV import requires admin role
413 File exceeds 5 MB Split into smaller files

Next steps