Inventory Import

Import inventory data via JSON payload or CSV file upload

The Inventory Import API allows external systems to create and update inventory records in Claret. The API supports two methods: JSON payloads for direct integrations and CSV file uploads with optional field mapping.

As with all Claret API endpoints, the Inventory Import API requires token authentication. For instructions on how to retrieve and pass through the authentication token, please refer to the Authentication documentation.

All API documentation herein contains a {tenant} section of the URL path. These should always be replaced with the name of the actual tenant making the API call (i.e., demo, yourcompany, etc.)

POST Inventory Import

POST https://plan.claret.app/{tenant}/api/v1/inventory/import/process

Import inventory records using either JSON payload or CSV file upload.

Rate Limits:

• Maximum 1000 records per request

Request Methods

The API supports two methods for importing inventory data:

Method	Content-Type	Response Code	Job Monitoring
JSON Payload	application/json	200 OK	Via UI link only
CSV File Upload	multipart/form-data	202 Accepted	Via job_log_id (programmatic)

Which method should I use?

• Use JSON Payload for direct API integrations where you construct records programmatically

• Use CSV File Upload when exporting data from external systems or when you need programmatic job status monitoring via job_log_id

---

JSON Payload Method

Use this method for direct API integrations where you construct inventory records programmatically.

Headers

Name	Value
Content-Type	application/json
Authorization	Bearer {token}

Request Body

Name	Type	Description
source*	string	Must be "api" for API requests
arguments*	object	Processing options (see below)
payload*	array	Array of inventory records to import
(arguments) allow_record_creation*	boolean	Allow creating new inventory records
(arguments) allow_record_update*	boolean	Allow updating existing records
(arguments) should_continue_on_error*	boolean	Continue processing if errors occur
(payload) item_name*	string	Item name (must exist in Claret)
(payload) bin_name*	string	Bin name (must exist in Claret)
(payload) lot_name*	string	Lot name (must exist in Claret)
(payload) date_filled*	string	Date inventory was filled. Format: YYYY-MM-DD
(payload) quantity*	number	Quantity amount (positive number)
(payload) uom*	string	Unit of measure (name or abbreviation)

200: OK Import Started

{
  "message": "Data import process started successfully. You will receive an email notification when the import completes.",
  "job_status_link": "https://plan.claret.app/{tenant}/settings/application-maintenance/job-management/imports/logs/12345"
}

422: Unprocessable Entity Validation Failed

Example: JSON Payload Request

curl -X POST "https://plan.claret.app/{tenant}/api/v1/inventory/import/process" \
  -H "Authorization: Bearer {your-token}" \
  -H "Content-Type: application/json" \
  -d '{
    "source": "api",
    "arguments": {
      "allow_record_creation": true,
      "allow_record_update": true,
      "should_continue_on_error": false
    },
    "payload": [
      {
        "item_name": "WIP-2024-CHARD",
        "bin_name": "TANK-A1",
        "lot_name": "LOT-2024-01",
        "date_filled": "2024-03-15",
        "quantity": 5000,
        "uom": "Gallon"
      }
    ]
  }'

---

CSV File Upload Method

Use this method when exporting data from external systems or when you need programmatic job status monitoring.

Headers

Name	Value
Content-Type	multipart/form-data
Authorization	Bearer {token}

Form Fields

Name	Type	Description
file*	file	CSV file to upload (max 10MB)
arguments*	JSON string	Processing options (see below)
field_mappings	JSON string	Required when headers_match_exactly is false

Arguments Object

Name	Type	Description
headers_match_exactly	boolean	Set true if CSV headers match staging column names exactly
allow_record_creation*	boolean	Allow creating new inventory records
allow_record_update*	boolean	Allow updating existing records
should_continue_on_error*	boolean	Continue processing if errors occur

Option A: CSV with Exact Headers

When your CSV file has headers that exactly match Claret's expected column names.

Required CSV Headers:

• item_name

• bin_name

• lot_name

• date_filled

• quantity

• uom

curl -X POST "https://plan.claret.app/{tenant}/api/v1/inventory/import/process" \
  -H "Authorization: Bearer {your-token}" \
  -F "[email protected]" \
  -F 'arguments={"headers_match_exactly":true,"allow_record_creation":true,"allow_record_update":true,"should_continue_on_error":false}'

Option B: CSV with Custom Headers + Field Mapping

When your CSV file has custom headers (e.g., exports fromm other systems), provide a mapping to Claret's column names.

Field Mappings Object: Maps your CSV headers to Claret's staging column names.

{
  "Your CSV Header": "claret_column_name"
}

Valid Claret Column Names:

• item_name

• bin_name

• lot_name

• date_filled

• quantity

• uom

curl -X POST "https://plan.claret.app/{tenant}/api/v1/inventory/import/process" \
  -H "Authorization: Bearer {your-token}" \
  -F "file=@inventory_export.csv" \
  -F 'arguments={"headers_match_exactly":false,"allow_record_creation":true,"allow_record_update":true,"should_continue_on_error":false}' \
  -F 'field_mappings={"Product Name":"item_name","Tank":"bin_name","Lot Number":"lot_name","Date":"date_filled","Volume":"quantity","Unit":"uom"}'

202: Accepted File Upload Started

{
  "message": "Data import process started successfully. Check job status for updates.",
  "job_log_id": 12345,
  "job_status_link": "https://plan.claret.app/{tenant}/settings/application-maintenance/job-management/imports/logs/12345"
}

422: Unprocessable Entity Header Mismatch

422: Unprocessable Entity Invalid File

---

Checking Job Status

For CSV file uploads, use the returned job_log_id to programmatically monitor import progress.

See the Job Status documentation for details on the status endpoint.

curl -X GET "https://plan.claret.app/{tenant}/api/v1/imports/status/12345" \
  -H "Authorization: Bearer {your-token}"

---

Pre-requisites

Before importing inventory via the API, ensure these entities exist in Claret:

Entity	Requirement
Items	Must exist with exact name matching item_name
Bins	Must exist with exact name matching bin_name
Lots	Must exist with exact name matching lot_name
UOMs	Must exist with name or abbreviation matching uom

All entity matches are case-sensitive. Ensure the names in your import data exactly match the values configured in Claret.

---

Common Errors

Error Message	Cause	Solution
Invalid payload structure	Single object instead of array	Wrap record in array: [{...}]
Item with name '...' does not exist	Item name mismatch	Verify item exists in Claret, check exact name
Bin with name '...' does not exist	Bin name mismatch	Verify bin exists in Claret, check exact name
Invalid file type. Only CSV files are allowed.	Non-CSV file uploaded	Upload a valid CSV file (.csv extension)
File size exceeds maximum allowed size of 10MB	File too large	Split into multiple smaller files
Field mappings are required	Missing field_mappings when headers don't match	Provide field_mappings parameter
Invalid mapping target	Invalid Claret column name in mapping	Use only: item_name, bin_name, lot_name, date_filled, quantity, uom