> ## Documentation Index
> Fetch the complete documentation index at: https://betterdatainc.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Import API Reference

> Endpoint reference for import payloads and job processing.

## Common Behavior

All import endpoints are asynchronous and return `202 Accepted` with a job envelope.

<ParamField body="x-api-key" type="string" required>
  API key with `import:read` or `import:write` scope.
</ParamField>

Each endpoint validates row payloads and reports row-level failures in job status.

## Endpoints

### Catalog Import

`POST /api/import/catalog`

<ParamField body="products" type="array" required>
  Array of catalog rows.
</ParamField>

<ParamField body="products[].externalId" type="string" required>
  Unique product identifier.
</ParamField>

<ParamField body="products[].name" type="string">
  Product name; defaults to `externalId` if omitted.
</ParamField>

### Inventory Import

`POST /api/import/inventory`

<ParamField body="levels" type="array" required>
  Array of inventory level rows.
</ParamField>

<ParamField body="levels[].skuId" type="string" required>
  SKU identifier.
</ParamField>

<ParamField body="levels[].locationId" type="string" required>
  Location code; internally normalized as `{organizationId}-{locationId}`.
</ParamField>

<ParamField body="levels[].quantityOnHand" type="number">
  Physical stock on hand. Defaults to `0`.
</ParamField>

<ParamField body="levels[].quantityReserved" type="number">
  Reserved quantity. Defaults to `0`.
</ParamField>

<ParamField body="levels[].reorderPoint" type="number">
  Threshold used to update internal minimum quantity. Defaults to `0`.
</ParamField>

### Suppliers Import

`POST /api/import/suppliers`

<ParamField body="suppliers" type="array" required>
  Array of supplier rows.
</ParamField>

<ParamField body="suppliers[].externalId" type="string" required>
  Unique supplier identifier.
</ParamField>

### Purchase Orders Import

`POST /api/import/purchase-orders`

<ParamField body="purchaseOrders" type="array" required>
  Array of purchase order headers.
</ParamField>

<ParamField body="purchaseOrders[].externalPoNumber" type="string" required>
  Purchase order number (idempotent key).
</ParamField>

<ParamField body="purchaseOrders[].supplierId" type="string" required>
  Supplier code.
</ParamField>

<ParamField body="purchaseOrders[].destinationLocationId" type="string" required>
  Destination location code.
</ParamField>

<ParamField body="purchaseOrders[].status" type="string">
  Optional PO status, defaults to `PENDING`.
</ParamField>

<ParamField body="purchaseOrders[].lines" type="array" required>
  PO line rows.
</ParamField>

<ParamField body="purchaseOrders[].lines[].skuId" type="string" required>
  SKU for the line.
</ParamField>

<ParamField body="purchaseOrders[].lines[].quantity" type="number" required>
  Line quantity.
</ParamField>

<ParamField body="purchaseOrders[].lines[].unitCost" type="number" required>
  Line unit cost.
</ParamField>

### Orders Import

`POST /api/import/orders`

<ParamField body="orders" type="array" required>
  Array of customer order headers.
</ParamField>

<ParamField body="orders[].externalOrderId" type="string" required>
  External order identifier.
</ParamField>

<ParamField body="orders[].lines" type="array" required>
  Order lines.
</ParamField>

<ParamField body="orders[].lines[].skuId" type="string" required>
  SKU identifier.
</ParamField>

<ParamField body="orders[].lines[].quantity" type="number" required>
  Requested quantity.
</ParamField>

<ParamField body="orders[].lines[].locationId" type="string" required>
  Fulfillment location code.
</ParamField>

### Demand History Import

`POST /api/import/demand-history`

<ParamField body="records" type="array" required>
  Array of weekly demand history records.
</ParamField>

<ParamField body="records[].skuId" type="string" required>
  SKU identifier.
</ParamField>

<ParamField body="records[].locationId" type="string" required>
  Location code.
</ParamField>

<ParamField body="records[].weekStarting" type="string" required>
  ISO date used to bucket weekly demand.
</ParamField>

<ParamField body="records[].channel" type="string">
  Channel label; defaults to `ALL`.
</ParamField>

<ParamField body="records[].actualDemand" type="number">
  Actual units; defaults to `0`.
</ParamField>

<ParamField body="records[].forecastedDemand" type="number">
  Forecast units; defaults to `actualDemand`.
</ParamField>

## Job Status

### Get Job Status

`GET /api/import/status/[jobId]`

<ResponseField name="jobId" type="string">
  Import job ID.
</ResponseField>

<ResponseField name="status" type="string">
  Current state (`PENDING`, `PROCESSING`, `COMPLETED`, `FAILED`).
</ResponseField>

<ResponseField name="rowCount" type="number">
  Total rows submitted.
</ResponseField>

<ResponseField name="processedCount" type="number">
  Rows processed.
</ResponseField>

<ResponseField name="failedCount" type="number">
  Rows rejected.
</ResponseField>

<ResponseField name="errors" type="array">
  Row-level error details.
</ResponseField>

<ResponseField name="completedAt" type="string | null">
  Completion timestamp when available.
</ResponseField>