Bulk Operations

Bulk endpoints let you operate on multiple records in a single request, reducing round-trips for high-volume scenarios.

Bulk Order Creation

Create multiple orders atomically. If any order fails validation, the entire batch is rejected.

curl -X POST http://localhost:8787/api/orders/bulk \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{
    "orders": [
      {
        "customerId": "cust-001",
        "lineItems": [
          { "skuId": "sku-pla-black-cube", "quantity": 1 }
        ]
      },
      {
        "customerId": "cust-002",
        "lineItems": [
          { "skuId": "sku-pla-white-panel", "quantity": 5 }
        ]
      }
    ]
  }'

Response:

{
  "created": 2,
  "failed": 0,
  "orders": [
    { "id": "ord-001", "status": "pending_payment" },
    { "id": "ord-002", "status": "pending_payment" }
  ]
}

Bulk Job Status Update

Advance multiple jobs to the same state at once — useful after a batch of prints completes:

curl -X POST http://localhost:8787/api/jobs/bulk/advance \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{
    "jobIds": ["job-001", "job-002", "job-003"],
    "targetStatus": "POST_PROCESS"
  }'

Bulk Cancel

Cancel multiple jobs or orders with a single request:

curl -X POST http://localhost:8787/api/jobs/bulk/cancel \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{
    "jobIds": ["job-001", "job-002"],
    "reason": "Material out of stock"
  }'

Bulk SKU Import

Import a catalog of SKUs from a JSON array. Existing SKUs (matched by id) are updated; new ones are created.

curl -X POST http://localhost:8787/api/skus/bulk \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-admin-key" \
  -d '{
    "skus": [ ...array of SKU objects... ],
    "mode": "upsert"
  }'

mode options:

upsert — create or update (default)
replace — deactivate all existing SKUs, then create new ones
append — create only; skip existing IDs

Rate Limits for Bulk Operations

Bulk endpoints have separate, higher rate limits:

Endpoint	Max items/request	Requests/min
`POST /api/orders/bulk`	50 orders	10
`POST /api/jobs/bulk/*`	100 jobs	20
`POST /api/skus/bulk`	500 SKUs	5