Update Inventory

This page describes the request data identifiers and response structure required to update per-variant inventory.

Data Identifier

{
  "dataID": "UPDATE_INVENTORY",
  "variant_seq": 5001,
  "quantity_on_hand": 10,
  "reorder_level": 2,
  "version_no": 0
}
KeyDescription
dataIDData identifier UPDATE_INVENTORY
variant_seqOption row number (variants[n].seq)
quantity_on_handNew stock on hand. 422 if below reserved
reorder_levelLow-stock level. Empty keeps it
version_noversion_no you loaded. 409 if it changed

HTML

<form id="frm_update_inventory" method="post">
  <input type="hidden" name="variant_seq" value="5001">
  <input type="number" name="quantity_on_hand" value="10" min="0">
  <input type="number" name="reorder_level" value="2" min="0">
  <input type="hidden" name="version_no" value="0">
  <button type="submit" class="btn btn-primary">Save</button>
</form>

Response Result

{
  "result": true,
  "result_code": 200,
  "variant_seq": 5001,
  "version_no": 1,
  "message": "updated"
}
KeyDescription
resultSucceeded or not
result_code200 saved, 409 version conflict, 422 below reserved
variant_seqRow number you sent
version_noNew stock version
messageMessage
  • quantity_reserved is ignored if sent. Orders manage reservations on placement, shipping and cancellation, so show it read-only.
  • Stock: available = on hand (quantity_on_hand) − reserved (quantity_reserved). The server adds reservations when an order is placed and releases them on shipping or cancellation.
  • Screen example: read rows and version_no with GET_PRODUCT_VARIANTS, replace version_no with the response value after saving, and ask the user to reload on 409.
  • Error codes — errors also come back as HTTP 200. Check result:false, then error_code (string) and error_message.
  • 401 — Sign-in required (Unauthorized).
  • 409 — Stock changed elsewhere (version conflict). This response has both error_code and result_code.
  • 422 — On hand would be lower than the reserved quantity.

Example

Available = on hand - reserved = 10

<script setup>
import { ref } from 'vue'
// Load the row from GET_PRODUCT_VARIANTS first and send its version_no back.
const form = ref({ variant_seq: 5001, quantity_on_hand: 10, reorder_level: 2, version_no: 0 })
const reserved = 0               // read-only: reservations are managed by orders
const msg = ref('')
async function save() {
  const { output } = await useNuxtApp().$connector({ dataID: 'UPDATE_INVENTORY', ...form.value })
  if (output.result) {
    form.value.version_no = output.version_no
    msg.value = 'Saved'
  } else if (output.error_code === '409') {
    msg.value = 'Stock was changed elsewhere. Reload and try again.'
  } else {
    msg.value = output.error_message      // 422: on hand is lower than reserved
  }
}
</script>

<template>
  <form class="card shadow-sm p-4" @submit.prevent="save">
    <div class="row g-3">
      <div class="col-md-4"><label class="form-label">On hand</label><input type="number" min="0" class="form-control" v-model.number="form.quantity_on_hand"></div>
      <div class="col-md-4"><label class="form-label">Reserved</label><input class="form-control" :value="reserved" readonly></div>
      <div class="col-md-4"><label class="form-label">Reorder level</label><input type="number" min="0" class="form-control" v-model.number="form.reorder_level"></div>
    </div>
    <p class="mt-2 text-secondary">Available = on hand - reserved = {{ form.quantity_on_hand - reserved }}</p>
    <button class="btn btn-primary">Save</button>
    <p class="mt-2">{{ msg }}</p>
  </form>
</template>
<?php
$requestData = [
    'dataID'           => 'UPDATE_INVENTORY',
    'variant_seq'      => 5001,
    'quantity_on_hand' => 10,      // must not be lower than the current reservations (422)
    'reorder_level'    => 2,
    'version_no'       => 0,       // from GET_PRODUCT_VARIANTS; 409 if someone changed it
];
$output = $connector->request($requestData);
echo $output['result'] ? 'Saved (version ' . $output['version_no'] . ')' : htmlspecialchars($output['error_message']);