Inventory

Always applies integration warehouse restrictions. Shipping-only credentials receive origin/capability metadata, not inventory balances.

Required permissions

{
  "anyOf": [
    {
      "allOf": [
        "inventory.read"
      ]
    },
    {
      "allOf": [
        "fulfillments.read"
      ]
    },
    {
      "allOf": [
        "rates.read"
      ]
    }
  ]
}

Parameters

Response

Discover locations in authorized warehouses.

Required permissions

{
  "anyOf": [
    {
      "allOf": [
        "inventory.read"
      ]
    }
  ]
}

Parameters

Response

Read product-by-warehouse stock balances. Incremental updatedAfter follows persisted balance-row changes. Derived supply or pick allocations are evaluated at read time and may change without advancing that row timestamp; periodically perform a full read for these derived quantities. Opaque version values support equality checks, not numeric ordering.

Required permissions

{
  "anyOf": [
    {
      "allOf": [
        "inventory.read"
      ]
    }
  ]
}

Parameters

Response

Read location-level physical stock. Incremental updatedAfter follows persisted balance-row changes. Derived supply or pick allocations are evaluated at read time and may change without advancing that row timestamp; periodically perform a full read for these derived quantities. Opaque version values support equality checks, not numeric ordering.

Required permissions

{
  "anyOf": [
    {
      "allOf": [
        "inventory.read"
      ]
    }
  ]
}

Parameters

Response

Stable order by occurredAt,id. No transaction mutation endpoints. These records represent executed business changes, not requested future quantities. Source order, fulfillment and store references must also be within the credential resource restrictions before pagination. A restricted ledger may contain fewer rows than the full physical warehouse ledger; stock quantities are never reduced to match those visible rows.

Required permissions

{
  "anyOf": [
    {
      "allOf": [
        "inventory.read"
      ]
    }
  ]
}

Parameters

Response

Apply an atomic guarded stock adjustment.

Required permissions

{
  "anyOf": [
    {
      "allOf": [
        "inventory.adjust"
      ]
    }
  ]
}

Parameters

Request

{
  "warehouseId": "10",
  "reasonCode": "correction",
  "reason": "Cycle check found two additional units",
  "lines": [
    {
      "productId": "501",
      "locationId": "22",
      "mode": "delta",
      "quantityDelta": 2,
      "expectedOnHand": 20
    }
  ]
}

Response

Create a manual warehouse-level stock hold.

Required permissions

{
  "anyOf": [
    {
      "allOf": [
        "inventory.reserve"
      ]
    }
  ]
}

Parameters

Request

{
  "warehouseId": "10",
  "productId": "501",
  "quantity": 3,
  "reason": "Reserved for upcoming promotion",
  "expiresAt": "2026-11-03 18:00:00"
}

Response

Only active manual holds; fully released/expired rows are not retained as resources by the current model. Audit/operation receipts are separate. Fulfillment holds are not editable here.

Required permissions

{
  "anyOf": [
    {
      "allOf": [
        "inventory.read"
      ]
    }
  ]
}

Parameters

Response

Release all or part of a manual stock hold.

Required permissions

{
  "anyOf": [
    {
      "allOf": [
        "inventory.reserve"
      ]
    }
  ]
}

Parameters

Request

{
  "quantity": 1,
  "reason": "Promotion requirement reduced"
}

Response