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"
}
}
| Key | Description |
|---|---|
| dataID | Data identifier UPDATE_ORDER_ITEM_STATUS |
| order_item_seq | Item number (order.items[n].seq) |
| to_status | New status |
| reason_code | Reason code (kept in history) |
| reason_text | Reason text (kept in history) |
| meta_data | Extra 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"
}
| Key | Description |
|---|---|
| result | Changed or not (true / false) |
| result_code | 200 on success |
| order_item_seq | Item number |
| order_seq | Order number |
| from_status | Previous status |
| to_status | New status |
| summary_status | Recalculated 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.
<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
}
User Discussions
ADD- There are no posts yet.