Inventory API

List Inventory

Returns inventory levels for products. Each record represents the stock quantity for a specific product variant at a specific warehouse location. Use this to synchronize stock levels between MallPlus and your WMS.

Query Parameters

Example Request

curl -X GET "https://api.mallplus.com/open/v1/inventory?product_id=prod_abc123" \
  -H "X-MallPlus-Partner-Id: app_ck9x2mf3w0001" \
  -H "X-MallPlus-Timestamp: 1713254400" \
  -H "X-MallPlus-Signature: a1b2c3d4e5f6..."

Example Response

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "inv_001",
        "product_id": "prod_abc123",
        "variant_id": "var_001",
        "sku": "WALLET-BLK-001",
        "warehouse_id": "wh_manila",
        "warehouse_name": "Manila Central Warehouse",
        "quantity": 45,
        "reserved": 3,
        "available": 42,
        "updated_at": "2026-04-15T12:00:00Z"
      },
      {
        "id": "inv_002",
        "product_id": "prod_abc123",
        "variant_id": "var_002",
        "sku": "WALLET-BRN-001",
        "warehouse_id": "wh_manila",
        "warehouse_name": "Manila Central Warehouse",
        "quantity": 32,
        "reserved": 1,
        "available": 31,
        "updated_at": "2026-04-15T12:00:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 2,
      "total_pages": 1
    }
  }
}

Update Inventory

Updates the stock quantity for a specific inventory record. Use this endpoint to synchronize stock levels from your WMS back into MallPlus. You can set an absolute quantity or provide a delta adjustment.

Request Body

Example Request

curl -X PUT "https://api.mallplus.com/open/v1/inventory/inv_001" \
  -H "Content-Type: application/json" \
  -H "X-MallPlus-Partner-Id: app_ck9x2mf3w0001" \
  -H "X-MallPlus-Timestamp: 1713254400" \
  -H "X-MallPlus-Signature: a1b2c3d4e5f6..." \
  -d '{
    "adjustment": -5,
    "reason": "WMS stock reconciliation"
  }'

Example Response

{
  "success": true,
  "data": {
    "id": "inv_001",
    "product_id": "prod_abc123",
    "variant_id": "var_001",
    "sku": "WALLET-BLK-001",
    "warehouse_id": "wh_manila",
    "quantity": 40,
    "reserved": 3,
    "available": 37,
    "updated_at": "2026-04-16T10:00:00Z"
  }
}

Bulk Update Inventory

Update stock quantities for multiple items in a single request. Maximum 100 items per batch. This is the recommended endpoint for WMS stock synchronization — significantly more efficient than individual updates.

Request Body

Example Request

curl -X POST "https://api.mallplus.com/open/v1/inventory/bulk-update" \
  -H "Content-Type: application/json" \
  -H "X-MallPlus-Partner-Id: app_ck9x2mf3w0001" \
  -H "X-MallPlus-Timestamp: 1713254400" \
  -H "X-MallPlus-Signature: a1b2c3d4e5f6..." \
  -d '{
    "items": [
      { "id": "prod_abc123", "quantity": 50 },
      { "id": "prod_def456", "quantity": 200 }
    ]
  }'

Example Response

{
  "success": true,
  "data": {
    "updated": [
      { "id": "prod_abc123", "sku": "ELEC-1001", "quantity": 50 },
      { "id": "prod_def456", "sku": "FASH-2001", "quantity": 200 }
    ],
    "errors": [],
    "summary": { "total": 2, "succeeded": 2, "failed": 0 }
  }
}

Get Variant Stock

Returns every variant of a product with its SKU and current on-hand stock at your store's stock location. stock_quantity is the on-hand stocked count — it is not reduced by quantities reserved for open orders, so it matches the physical count in your warehouse. Use variant_id and sku to map each variant to your WMS records.

Path Parameters

Response Fields (per variant)

Example Request

curl -X GET "https://api.mallplus.com/open/v1/products/prod_abc123/variants" \
  -H "X-MallPlus-Partner-Id: app_ck9x2mf3w0001" \
  -H "X-MallPlus-Timestamp: 1713254400" \
  -H "X-MallPlus-Signature: a1b2c3d4e5f6..."

Example Response

{
  "success": true,
  "data": [
    { "variant_id": "var_001", "sku": "WALLET-BLK-001", "stock_quantity": 45 },
    { "variant_id": "var_002", "sku": "WALLET-BRN-001", "stock_quantity": 32 }
  ]
}

Update Variant Stock

Sets the absolute on-hand stock quantity for one or more variants of a product after a warehouse goods movement or stock count. Every variant in the request is validated before anything is written: if any variant_id is invalid or does not belong to the product, the entire request is rejected with 400 identifying the offending variant, and no stock is changed. A negative stock_quantity also returns 400. Reserved quantities for open orders are preserved. Supports the Idempotency-Key header for safe retries.

Request Body

Example Request

curl -X PUT "https://api.mallplus.com/open/v1/products/prod_abc123/stock" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 9f1c8a30-2b7e-4c4a-9d2e-1f6b3c8e7a02" \
  -H "X-MallPlus-Partner-Id: app_ck9x2mf3w0001" \
  -H "X-MallPlus-Timestamp: 1713254400" \
  -H "X-MallPlus-Signature: a1b2c3d4e5f6..." \
  -d '{
    "items": [
      { "variant_id": "var_001", "stock_quantity": 50 },
      { "variant_id": "var_002", "stock_quantity": 200 }
    ]
  }'

Example Response

{
  "success": true,
  "data": {
    "items": [
      { "variant_id": "var_001", "stock_quantity": 50 },
      { "variant_id": "var_002", "stock_quantity": 200 }
    ]
  }
}