inventory.reserve

Atomically hold stock for a set of (sku, qty) lines — all-or-nothing, idempotent. A line with no warehouse is routed (lowest priority with stock; the default breaks ties); a line no warehouse can hold is refused, unless the routed warehouse sells past zero, in which case it is held as a backorder.

• Scope: inventory.reserve
• System: no
• Reachable from: POST /v1/commands/inventory.reserve (tenant credential) · MCP tool inventory.reserve · SDK client.call('inventory.reserve', …)
• Events: inventory.reserved

Input (JSON Schema)

{
  "properties": {
    "lines": {
      "items": {
        "properties": {
          "qty": {
            "exclusiveMinimum": 0,
            "maximum": 9007199254740991,
            "type": "integer"
          },
          "sku_id": {
            "minLength": 1,
            "type": "string"
          },
          "warehouse_id": {
            "type": "string"
          }
        },
        "required": [
          "sku_id",
          "qty"
        ],
        "type": "object"
      },
      "minItems": 1,
      "type": "array"
    },
    "ttl_seconds": {
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "type": "integer"
    }
  },
  "required": [
    "lines"
  ],
  "type": "object"
}

Result (200)

{
  "additionalProperties": false,
  "properties": {
    "expires_at": {
      "type": "string"
    },
    "reservation_id": {
      "type": "string"
    }
  },
  "required": [
    "reservation_id",
    "expires_at"
  ],
  "type": "object"
}

Errors

validation_failed (400) · unauthorized (401) · forbidden (403) · conflict (409) · internal (500)