Inventory

Set and query on-hand quantities by location and product.

• Base path: /api/integrations/v1/inventory/
• Required scope: integrations.inventory.{read|write} — see Scopes.

info

Inventory isn't a per-record CRUD resource. A record represents the quantity of a product at a location. Quantities are upserted through a single bulk endpoint.

---

Bulk set inventory

POST /api/integrations/v1/inventory/

Upserts one or more (location, product) pairs. Existing records are updated; missing ones are created.

Body

Field	Type	Required	Description
inventory	array	Yes	Non-empty list of records
inventory[].location_code	string	Yes	Location code
inventory[].sku_code	string	Yes	Product SKU
inventory[].quantity	integer	Yes	Minimum 0
source	string	No	bulk_import, manual_adjustment, erp_sync, initial_load (default bulk_import)
notes	string	No	Free-form

curl

curl -X POST https://<your-tenant>.datamingle.ai/api/integrations/v1/inventory/ \
  -H "X-API-Key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "inventory": [
      {"location_code": "A-101", "sku_code": "RUG-5X7-BLU", "quantity": 150},
      {"location_code": "A-101", "sku_code": "RUG-8X10-RED", "quantity": 75},
      {"location_code": "B-201", "sku_code": "RUG-5X7-BLU", "quantity": 200}
    ],
    "source": "erp_sync",
    "notes": "Daily inventory sync"
  }'

Python

import requests

res = requests.post(
    "https://<your-tenant>.datamingle.ai/api/integrations/v1/inventory/",
    headers={"X-API-Key": "sk_live_..."},
    json={
        "inventory": [
            {"location_code": "A-101", "sku_code": "RUG-5X7-BLU", "quantity": 150},
            {"location_code": "A-101", "sku_code": "RUG-8X10-RED", "quantity": 75},
            {"location_code": "B-201", "sku_code": "RUG-5X7-BLU", "quantity": 200},
        ],
        "source": "erp_sync",
    },
    timeout=60,
)
res.raise_for_status()
summary = res.json()["data"]

Node.js

const res = await fetch(
  "https://<your-tenant>.datamingle.ai/api/integrations/v1/inventory/",
  {
    method: "POST",
    headers: {
      "X-API-Key": "sk_live_...",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      inventory: [
        { location_code: "A-101", sku_code: "RUG-5X7-BLU", quantity: 150 },
        { location_code: "A-101", sku_code: "RUG-8X10-RED", quantity: 75 },
        { location_code: "B-201", sku_code: "RUG-5X7-BLU", quantity: 200 },
      ],
      source: "erp_sync",
    }),
  },
);
const { data: summary } = await res.json();

Response 200 OK

{
  "success": true,
  "data": {
    "total": 3,
    "created": 2,
    "updated": 1,
    "failed": 0,
    "errors": []
  }
}

Partial failure

Rows are evaluated independently. Invalid rows are reported in errors[]; valid rows still succeed.

{
  "success": true,
  "data": {
    "total": 3,
    "created": 2,
    "updated": 0,
    "failed": 1,
    "errors": [
      {
        "row": 2,
        "location_id": "INVALID-LOC",
        "product_id": "RUG-5X7-BLU",
        "errors": {"location_id": ["Location not found"]}
      }
    ]
  }
}

Errors

Status	Code	When
400	VALIDATION_ERROR	inventory missing, empty, or not a list
422	MAPPING_ERROR	Mapping engine failed

---

List inventory

GET /api/integrations/v1/inventory/

Returns a cursor-paginated list of inventory records across all locations, newest-first.

Query parameters: limit (1–200, default 50), cursor (opaque). See Pagination.

curl 'https://<your-tenant>.datamingle.ai/api/integrations/v1/inventory/?limit=100' \
  -H "X-API-Key: sk_live_..."

Response 200 OK

{
  "success": true,
  "data": [
    {"location_code": "A-101", "sku_code": "RUG-5X7-BLU", "quantity": 150},
    {"location_code": "A-101", "sku_code": "RUG-8X10-RED", "quantity": 75}
  ],
  "pagination": {"limit": 100, "next_cursor": "eyJjIjoi..."}
}

---

Get inventory by location or SKU

GET /api/integrations/v1/inventory/{identifier}/

Two-way lookup controlled by the ?by query parameter.

?by	{identifier} is	Returns
location (default)	A location_code	Every SKU held at that location
sku	A sku_code	Every location holding that SKU

An empty array means no matching records exist.

Response shape (uniform for both modes)

{
  "success": true,
  "data": [
    {"location_code": "A-101", "sku_code": "RUG-5X7-BLU", "quantity": 150},
    {"location_code": "A-101", "sku_code": "RUG-8X10-RED", "quantity": 75}
  ]
}

Get everything at a location (default)

curl https://<your-tenant>.datamingle.ai/api/integrations/v1/inventory/A-101/ \
  -H "X-API-Key: sk_live_..."

?by=location is the default and may be omitted.

Find every location holding a SKU

curl 'https://<your-tenant>.datamingle.ai/api/integrations/v1/inventory/RUG-5X7-BLU/?by=sku' \
  -H "X-API-Key: sk_live_..."

{
  "success": true,
  "data": [
    {"location_code": "A-101", "sku_code": "RUG-5X7-BLU", "quantity": 150},
    {"location_code": "B-201", "sku_code": "RUG-5X7-BLU", "quantity": 200}
  ]
}

Errors

Status	Code	When
400	VALIDATION_ERROR	by is present but not location or sku