Import Cartons
Bulk create or update cartons via CSV.
Bulk create or update cartons via CSV. Use this to configure standard package sizes in bulk, or to migrate cartons between environments.
CSV Columns
| Column | Required | Description |
|---|---|---|
id | No | Existing carton ID. If provided, updates the carton. If empty, creates a new one. |
name | Yes | Name for the carton (e.g., "Small Box", "Large Flat Rate") |
measurement_unit | Yes | Dimension unit: CM or IN |
length | Yes | Package length |
width | Yes | Package width |
height | Yes | Package height |
weight_unit | Yes | Weight unit: G, KG, LB, or OZ |
weight | Yes | Package weight |
default | Yes | true or false. Whether this is the default carton. |
created_at | No | Read-only. Ignored on import. |
updated_at | No | Read-only. Ignored on import. |
_lock (Do not modify) | No | Change detection hash. See Understanding _lock below. |
Understanding _lock
Export current records as your starting template. When an export includes _lock (Do not modify), keep its value and the existing row's id unchanged while editing other fields.
- Unchanged rows and edits already matching the saved record are skipped.
- If both the CSV and saved record changed since export, a conflicting edit is rejected. Export the latest data, review the other changes, and reapply your edit.
- A locked row without its original ID is rejected.
- For a new record, leave both the ID and lock empty.
- Omitting a lock on an existing record removes conflict protection; it does not force an otherwise invalid edit to succeed.
Adding New Entries
To add new cartons, add rows with both the id and _lock (Do not modify) columns left empty. The system creates new records.
Bulk delete is not supported. To remove cartons, delete them individually through the UI or API.
How to Import
- Navigate to ShipOS → Settings → Cartons (opens the Cybership dashboard in a new tab)
- Click Import
- Upload your CSV
- Import processes asynchronously via background job
- Monitor progress in real-time
- Review completion status and any errors
Wait for the job to finish and inspect created, updated, skipped, and failed rows. A row-based import can partly succeed. Correct failed rows before retrying; do not assume the whole file was rolled back or that repeating new rows is harmless.
Export existing cartons first to use as a template for your import. See Export Cartons.