Bulk Import (CSV/NDJSON)

Flow: Create job → Upload file(s) to S3 (presigned) → Complete job (validate & load) → (optional) download error report

---

1) Create an import job

POST https://api.omakase.ai/v1/imports/orders

Headers:

X-API-Key: <your-key>
Content-Type: application/json

Body:

{
  "format": "csv" | "ndjson",
  "compression": "none" | "gzip",
  "schemaVersion": "1.0",
  "uploadMode": "single" | "multipart" | "auto",
  "fileSizeBytes": 123456789  // optional hint for auto mode
}

Response (CSV example):

{
  "jobId": "uuid",
  "csvModel": "split",
  "uploadMode": "single",
  "expiresInSec": 1800,
  "files": {
    "ordersUrl": "https://s3...",
    "itemsUrl": "https://s3...",
    "fulfillmentUrl": "https://s3..."
  }
}

Response (NDJSON example):

{
  "jobId": "uuid",
  "uploadMode": "single",
  "presignedUrl": "https://s3...",
  "expiresInSec": 1800
}

Response (NDJSON multipart example):

{
  "jobId": "uuid",
  "uploadMode": "multipart",
  "uploadId": "abc123...",
  "partSizeBytes": 134217728
}

2) Upload to S3 (presigned URL)

Single-part upload:

PUT <presignedUrl>
Content-Type: application/octet-stream
-- raw bytes of your file --

Multipart (large files):

Get part URLs:

GET https://api.omakase.ai/v1/imports/{jobId}/multipart/parts?partNumber=1
GET https://api.omakase.ai/v1/imports/{jobId}/multipart/parts?partNumber=2
...

Response:

{
  "url": "https://s3...",
  "expiresInSec": 1800
}

Upload each part with PUT (use returned URL).

Complete multipart:

POST https://api.omakase.ai/v1/imports/{jobId}/multipart/complete
Content-Type: application/json

{
  "parts": [
    { "partNumber": 1, "etag": "<etag-from-s3>" },
    { "partNumber": 2, "etag": "<etag-from-s3>" }
  ]
}

3) Complete the job (validate & load)

POST https://api.omakase.ai/v1/imports/{jobId}/complete

Response:

{
  "jobId": "uuid",
  "state": "completed" | "completed_with_errors" | "failed",
  "load": {
    "received": 123,
    "applied": 120,
    "failed": 3
  },
  "reportUrl": "https://s3.../error-report.gz"  // present if errors
}

Poll status:

GET https://api.omakase.ai/v1/imports/{jobId}

Response:

{
  "jobId": "uuid",
  "organizationId": "uuid",
  "state": "pending" | "queued" | "validating" | "processing" | "completed" | "completed_with_errors" | "failed",
  "counts": {
    "received": 123,
    "applied": 120,
    "duplicates": 0,
    "failed": 3
  },
  "startedAt": "2025-11-10T10:00:00Z",
  "finishedAt": "2025-11-10T10:05:00Z",
  "fileUrls": {
    "ordersUrl": "https://s3...",
    "itemsUrl": "https://s3...",
    "fulfillmentUrl": "https://s3..."
  }
}

4) File formats

• CSV (split): three files with fixed headers

  • orders.csv

  • order_items.csv

  • fulfillment_events.csv

• NDJSON (single): one file where each line is a JSON record

Tip: Gzip large files. Set compression: "gzip" when creating the job.

Error handling

• Validation errors do not stop the job unless all records are invalid.

• An error report is uploaded when there are invalid rows; use reportUrl to download and fix.

• Get error report URL: GET https://api.omakase.ai/v1/imports/{jobId}/report

• Run validation only: POST https://api.omakase.ai/v1/imports/{jobId}/validate