Bulk Update Order Item Status

This page describes the request data identifiers and response structure required to bulk-update the status of multiple order items.

Data Identifier

{
  "dataID": "UPDATE_ORDER_ITEMS_STATUS",
  "order_key": "E477FEEBAABBCCDD208AFC505D20C022",
  "to_status": "PREPARING_SHIPMENT",
  "order_item_seq": [501],
  "dry_run": 1,
  "reason_code": "BATCH_PICK",
  "reason_text": "Picked for dispatch"
}
KeyDescription
dataIDData identifier UPDATE_ORDER_ITEMS_STATUS
order_keyOrder key (recommended)
order_seqOrder number (when no order_key)
to_statusNew status
order_item_seqItem array or comma list. Empty = all
dry_run1 = preview only, nothing saved
batch_keyBatch key (A-Z, 0-9, -, 8 to 64)
batch_sourceBatch source (a-z, _). Default order_list_bulk
reason_codeReason code (kept in history)
reason_textReason text (kept in history)
meta_dataExtra JSON (kept in history)

HTML

<div class="card p-4">
  <div class="d-flex gap-2">
    <select class="form-select" v-model="toStatus">
      <option>PREPARING_SHIPMENT</option><option>SHIPPED</option><option>DELIVERED</option>
    </select>
    <button class="btn btn-outline-secondary">Preview</button>
    <button class="btn btn-primary">Apply</button>
  </div>
  <p v-if="preview" class="mt-3 mb-0">
    {{ preview.changed_count }} will change, {{ preview.skipped_count }} skipped, {{ preview.rejected_count }} rejected
  </p>
</div>

Response Result

{
  "result": true,
  "result_code": 200,
  "order_seq": 123,
  "order_no": "ORD-20261004-CAA73C",
  "dry_run": false,
  "batch_key": null,
  "changed": [
    {
      "order_item_seq": 501,
      "order_seq": 123,
      "from_status": "PAID",
      "to_status": "PREPARING_SHIPMENT",
      "product_name": "Cotton T-Shirt"
    }
  ],
  "skipped": [],
  "rejected": [],
  "changed_count": 1,
  "skipped_count": 0,
  "rejected_count": 0,
  "summary_status": "PREPARING_SHIPMENT"
}
KeyDescription
resultProcessed or not (true / false)
order_seqOrder number
order_noOrder no
dry_runWhether it was a preview
batch_keyThe batch_key sent. null if none
changedItems changed (or to change)
skippedSkipped items (reason: already / terminal)
rejectedRejected (invalid_transition / not_found)
changed_countNumber of changed
skipped_countNumber of skipped
rejected_countNumber of rejected
summary_statusOrder summary (current value on preview)
  • Screen example: check items on the order detail, pick a status, show a dry_run=1 preview (to change, skipped, rejected), then call again without dry_run to apply.
  • Runs in one transaction. Items already in that status (already) or in a final status (terminal) are skipped; disallowed moves and item numbers not in this order are rejected; the rest change. Repeating the request does not duplicate history.
  • changed, skipped and rejected entries are {order_item_seq, from_status, product_name}; changed adds order_seq and to_status, the others add reason. See Change item status for allowed moves and stock effects.
  • Error codes — errors also come back as HTTP 200. Check result:false, then error_code (string) and error_message.
  • 401 — Login required. Every order API needs a signed-in session.
  • 404 — Order not found. The order_key is wrong or the order was deleted.
  • 400 — Both order_key and order_seq are empty.
  • 400 — to_status is empty or unknown (Invalid to_status), an invalid batch_key, or no valid number in order_item_seq.

Example

1 will change, 0 skipped, 0 rejected

<script setup>
import { ref } from 'vue'
const orderKey = 'E477FEEBAABBCCDD208AFC505D20C022'
const selected = ref([501])            // checked items. Leave empty to target every item
const toStatus = ref('PREPARING_SHIPMENT')
const preview = ref(null)
const done = ref(null)

function request(dryRun) {
  return useNuxtApp().$connector({
    dataID: 'UPDATE_ORDER_ITEMS_STATUS', order_key: orderKey, to_status: toStatus.value,
    order_item_seq: selected.value.length ? selected.value : undefined,
    dry_run: dryRun ? 1 : 0, reason_code: 'BATCH_PICK', reason_text: 'Picked for dispatch'
  })
}
// 1) Preview without saving
async function check() { preview.value = (await request(true)).output }
// 2) Apply
async function apply() { done.value = (await request(false)).output; preview.value = null }
</script>

<template>
  <div class="card p-4">
    <div class="d-flex gap-2">
      <select class="form-select" v-model="toStatus">
        <option>PREPARING_SHIPMENT</option><option>SHIPPED</option><option>DELIVERED</option>
      </select>
      <button class="btn btn-outline-secondary" @click="check">Preview</button>
      <button class="btn btn-primary" :disabled="!preview || !preview.changed_count" @click="apply">Apply</button>
    </div>
    <p v-if="preview" class="mt-3 mb-0">
      {{ preview.changed_count }} will change, {{ preview.skipped_count }} skipped, {{ preview.rejected_count }} rejected
    </p>
    <ul v-if="preview && preview.rejected_count" class="small mb-0">
      <li v-for="r in preview.rejected" :key="r.order_item_seq">{{ r.product_name }}: {{ r.from_status }} ({{ r.reason }})</li>
    </ul>
    <p v-if="done" class="mt-3 mb-0">{{ done.changed_count }} changed. Order is now {{ done.summary_status }}</p>
  </div>
</template>
<?php
$req = [
    'dataID'         => 'UPDATE_ORDER_ITEMS_STATUS',
    'order_key'      => 'E477FEEBAABBCCDD208AFC505D20C022',
    'to_status'      => 'PREPARING_SHIPMENT',
    'order_item_seq' => [501],          // omit to target every item in the order
    'reason_code'    => 'BATCH_PICK',
];
// 1) Preview (nothing is saved)
$preview = $connector->request($req + ['dry_run' => 1]);
echo $preview['changed_count'] . ' will change, ' . $preview['rejected_count'] . ' rejected';
// 2) Apply
if ($preview['changed_count'] > 0) {
    $output = $connector->request($req);
    echo 'Order is now ' . $output['summary_status'];
}