Orders

Create, list, retrieve, update, and cancel orders.

• Base path: /api/integrations/v1/orders/
• Required scope: integrations.orders.{read|write|delete} or wildcards above.
• Idempotency: POSTs are keyed by order_number. Re-sending the same payload returns a validation error on the duplicate — see Idempotency.

---

Create order

POST /api/integrations/v1/orders/

Body

Field	Type	Required	Description
order_number	string	Yes	Unique order number
external_order_id	string	No	Your system's ID; used for addressing the record
customer_name	string	No	Customer name
customer_info	object	No	Address, phone, any structured data
notes	string	No	Free-form notes
order_date	datetime	No	ISO 8601
due_date	datetime	No	ISO 8601
metadata	object	No	Arbitrary metadata
items	array	Yes	At least one line item
items[].sku_code	string	Yes	Must reference an existing product SKU
items[].quantity	integer	Yes	Minimum 1
items[].notes	string	No	Line notes

curl

curl -X POST https://<your-tenant>.datamingle.ai/api/integrations/v1/orders/ \
  -H "X-API-Key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "order_number": "ORD-2026-001",
    "external_order_id": "ERP-5001",
    "customer_name": "Acme Corporation",
    "customer_info": {"address": "123 Main St", "phone": "+1-555-0100"},
    "due_date": "2026-05-01T00:00:00Z",
    "items": [
      {"sku_code": "RUG-5X7-BLU", "quantity": 10},
      {"sku_code": "RUG-8X10-RED", "quantity": 5, "notes": "Fragile"}
    ]
  }'

Python

import requests

res = requests.post(
    "https://<your-tenant>.datamingle.ai/api/integrations/v1/orders/",
    headers={"X-API-Key": "sk_live_..."},
    json={
        "order_number": "ORD-2026-001",
        "external_order_id": "ERP-5001",
        "customer_name": "Acme Corporation",
        "due_date": "2026-05-01T00:00:00Z",
        "items": [
            {"sku_code": "RUG-5X7-BLU", "quantity": 10},
            {"sku_code": "RUG-8X10-RED", "quantity": 5, "notes": "Fragile"},
        ],
    },
    timeout=30,
)
res.raise_for_status()
order = res.json()["data"]

Node.js

const res = await fetch(
  "https://<your-tenant>.datamingle.ai/api/integrations/v1/orders/",
  {
    method: "POST",
    headers: {
      "X-API-Key": "sk_live_...",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      order_number: "ORD-2026-001",
      external_order_id: "ERP-5001",
      customer_name: "Acme Corporation",
      due_date: "2026-05-01T00:00:00Z",
      items: [
        { sku_code: "RUG-5X7-BLU", quantity: 10 },
        { sku_code: "RUG-8X10-RED", quantity: 5, notes: "Fragile" },
      ],
    }),
  },
);
if (!res.ok) throw new Error(await res.text());
const { data: order } = await res.json();

Response 201 Created

{
  "success": true,
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "order_number": "ORD-2026-001",
    "external_order_id": "ERP-5001",
    "customer_name": "Acme Corporation",
    "status": "pending",
    "items": [
      {
        "id": "...",
        "sku": {"sku": "RUG-5X7-BLU"},
        "quantity": 10,
        "verified_quantity": 0,
        "verification_status": "pending"
      }
    ],
    "created_at": "2026-04-16T10:00:00Z"
  }
}

Errors

Status	Code	When
400	VALIDATION_ERROR	Missing or invalid fields
400	SERVICE_ERROR	e.g. sku_code doesn't exist
422	MAPPING_ERROR	Field mapping engine failed on your payload
401	—	Invalid / expired key
403	—	Missing key or insufficient scope

---

List orders

GET /api/integrations/v1/orders/

Returns a cursor-paginated list ordered newest-first. Default page size 50, max 200 — full details in Pagination.

Query parameters: limit (1–200, default 50), cursor (opaque; use the previous response's pagination.next_cursor).

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

Response 200 OK

{
  "success": true,
  "data": [
    {
      "id": "...",
      "order_number": "ORD-001",
      "status": "pending",
      "customer_name": "Acme Corp",
      "created_at": "2026-04-16T10:00:00Z"
    }
  ],
  "pagination": {
    "limit": 100,
    "next_cursor": "eyJjIjoi..."
  }
}

---

Get order

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

{identifier} resolves according to your identifier configuration. Returns the full order shape (same as Create).

curl https://<your-tenant>.datamingle.ai/api/integrations/v1/orders/ERP-5001/ \
  -H "X-API-Key: sk_live_..."

Errors

Status	Code	When
404	NOT_FOUND	No order matches the identifier
401/403	—	Auth failure — see Authentication

---

Update order

PUT /api/integrations/v1/orders/{identifier}/

Only header fields can be updated. Line items are immutable through this endpoint.

Field	Type
customer_name	string
customer_info	object
notes	string
due_date	datetime
metadata	object
status	string

curl -X PUT https://<your-tenant>.datamingle.ai/api/integrations/v1/orders/ERP-5001/ \
  -H "X-API-Key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"customer_name": "Acme Corp (Updated)", "notes": "Rush"}'

Returns 200 OK with the full updated order.

---

Cancel order

DELETE /api/integrations/v1/orders/{identifier}/

Cancellation is soft — the order is kept, its status moves to cancelled.

Body (optional)

Field	Type	Description
reason	string	Cancellation reason

curl -X DELETE https://<your-tenant>.datamingle.ai/api/integrations/v1/orders/ERP-5001/ \
  -H "X-API-Key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"reason": "Customer requested cancellation"}'

Errors

Status	Code	When
400	SERVICE_ERROR	e.g. the order is already shipped
404	NOT_FOUND	No order matches the identifier

---

Order statuses

Status	Meaning
draft	Created, not yet active
pending	Active, awaiting verification
in_progress	At least one line item scanned
partially_verified	Some lines verified
verified	All lines verified
shipped	Shipped — cannot be cancelled
cancelled	Cancelled