Update Order Item Status

This page describes the request data identifiers and response structure required to change the status of a single order item.

Data Identifier

{
  "dataID": "UPDATE_ORDER_ITEM_STATUS",
  "order_item_seq": 501,
  "to_status": "PAID",
  "reason_code": "PAYMENT_CONFIRMED",
  "reason_text": "Payment confirmed",
  "meta_data": {
    "pg_tid": "T0000000000"
  }
}
KeyDescription
dataIDData identifier UPDATE_ORDER_ITEM_STATUS
order_item_seqItem number (order.items[n].seq)
to_statusNew status
reason_codeReason code (kept in history)
reason_textReason text (kept in history)
meta_dataExtra JSON (kept in history)

HTML

<div class="card p-4">
  <p>{{ item.product_name }} · current <strong>{{ item.item_status }}</strong></p>
  <div class="d-flex gap-2">
    <select class="form-select" v-model="toStatus">
      <option v-for="s in choices" :value="s">{{ s }}</option>
    </select>
    <input class="form-control" v-model="reason" placeholder="Reason">
    <button class="btn btn-primary">Apply</button>
  </div>
  <p class="mt-2 mb-0">{{ msg }}</p>
</div>

Response Result

{
  "result": true,
  "result_code": 200,
  "order_item_seq": 501,
  "order_seq": 123,
  "from_status": "RECEIVED",
  "to_status": "PAID",
  "summary_status": "PAID"
}
KeyDescription
resultChanged or not (true / false)
result_code200 on success
order_item_seqItem number
order_seqOrder number
from_statusPrevious status
to_statusNew status
summary_statusRecalculated order summary
  • Screen example: on each item row of the order detail, offer only the statuses allowed from the current one (see below). After the change, update the order badge with summary_status.
  • Item status flow: RECEIVED → PAYMENT_PENDING → PAID → PREPARING_SHIPMENT → SHIPPED → DELIVERED. Cancel: CANCEL_REQUESTED → CANCEL_PROCESSING → CANCELLED. Return: RETURN_REQUESTED → RETURN_PROCESSING → RETURNED. Exchange: EXCHANGE_REQUESTED → EXCHANGE_PROCESSING → EXCHANGED. CANCELLED, RETURNED and EXCHANGED are final.
  • Allowed moves (current → next): RECEIVED → PAYMENT_PENDING, PAID, CANCEL_REQUESTED, CANCELLED / PAYMENT_PENDING → PAID, CANCEL_REQUESTED, CANCELLED / PAID → PREPARING_SHIPMENT, CANCEL_REQUESTED, CANCELLED / PREPARING_SHIPMENT → SHIPPED, CANCEL_REQUESTED
  • SHIPPED → DELIVERED, RETURN_REQUESTED / DELIVERED → RETURN_REQUESTED, EXCHANGE_REQUESTED / CANCEL_REQUESTED → CANCEL_PROCESSING, CANCELLED, PAID (cancel rejected) / CANCEL_PROCESSING → CANCELLED
  • RETURN_REQUESTED → RETURN_PROCESSING, RETURNED, DELIVERED (return rejected) / RETURN_PROCESSING → RETURNED / EXCHANGE_REQUESTED → EXCHANGE_PROCESSING, EXCHANGED, DELIVERED (exchange rejected) / EXCHANGE_PROCESSING → EXCHANGED. Any other move returns 409.
  • Stock: placing an order reserves stock (quantity_reserved). SHIPPED takes it from both on-hand and reserved, CANCELLED before shipping releases the reservation, and RETURNED (or CANCELLED) after shipping restocks it. The server does this in the same transaction.
  • Save tracking numbers with the item shipping API. That API does not change status, so call this one to move the item to SHIPPED.
  • 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.
  • 400 — order_item_seq or to_status is empty.
  • 404 — Order item not found.
  • 409 — A move that is not allowed (Invalid status transition: PAID -> DELIVERED) or someone changed it first (changed concurrently). Reload and try again.

Example

Cotton T-Shirt · current PAID

RECEIVED → PAID (order: PAID)

<script setup>
import { ref, computed } from 'vue'
// Offer only the moves the server allows (anything else returns 409)
const NEXT = {
  RECEIVED: ['PAYMENT_PENDING', 'PAID', 'CANCEL_REQUESTED', 'CANCELLED'],
  PAYMENT_PENDING: ['PAID', 'CANCEL_REQUESTED', 'CANCELLED'],
  PAID: ['PREPARING_SHIPMENT', 'CANCEL_REQUESTED', 'CANCELLED'],
  PREPARING_SHIPMENT: ['SHIPPED', 'CANCEL_REQUESTED'],
  SHIPPED: ['DELIVERED', 'RETURN_REQUESTED'],
  DELIVERED: ['RETURN_REQUESTED', 'EXCHANGE_REQUESTED'],
  CANCEL_REQUESTED: ['CANCEL_PROCESSING', 'CANCELLED', 'PAID'],
  CANCEL_PROCESSING: ['CANCELLED'],
  RETURN_REQUESTED: ['RETURN_PROCESSING', 'RETURNED', 'DELIVERED'],
  RETURN_PROCESSING: ['RETURNED'],
  EXCHANGE_REQUESTED: ['EXCHANGE_PROCESSING', 'EXCHANGED', 'DELIVERED'],
  EXCHANGE_PROCESSING: ['EXCHANGED']
}
const item = ref({ seq: 501, product_name: 'Cotton T-Shirt', item_status: 'RECEIVED' })
const choices = computed(() => NEXT[item.value.item_status] || [])
const toStatus = ref('PAID')
const reason = ref('Payment confirmed')
const msg = ref('')

async function change() {
  const { output } = await useNuxtApp().$connector({
    dataID: 'UPDATE_ORDER_ITEM_STATUS', order_item_seq: item.value.seq,
    to_status: toStatus.value, reason_code: 'MANUAL', reason_text: reason.value
  })
  if (output.result) {
    item.value.item_status = output.to_status
    msg.value = `${output.from_status} → ${output.to_status} (order: ${output.summary_status})`
  } else {
    msg.value = output.error_message   // 409: Invalid status transition
  }
}
</script>

<template>
  <div class="card p-4">
    <p>{{ item.product_name }} · current <strong>{{ item.item_status }}</strong></p>
    <div class="d-flex gap-2">
      <select class="form-select" v-model="toStatus">
        <option v-for="s in choices" :key="s" :value="s">{{ s }}</option>
      </select>
      <input class="form-control" v-model="reason" placeholder="Reason">
      <button class="btn btn-primary" :disabled="!choices.length" @click="change">Apply</button>
    </div>
    <p class="mt-2 mb-0">{{ msg }}</p>
  </div>
</template>
<?php
$output = $connector->request([
    'dataID'         => 'UPDATE_ORDER_ITEM_STATUS',
    'order_item_seq' => 501,
    'to_status'      => 'PAID',
    'reason_code'    => 'PAYMENT_CONFIRMED',
    'reason_text'    => 'Payment confirmed',
]);
if ($output['result']) {
    echo $output['from_status'] . ' → ' . $output['to_status'] . ' (order: ' . $output['summary_status'] . ')';
} else {
    echo htmlspecialchars($output['error_message']);   // 409 Invalid status transition
}