The store API: change an order's status, and the allowed moves
The reference for the order status address of the ArabyBot store API: the fields, the allowed moves, the response, and the refusals.
On this page 7
The short answer
With a POST request to the status address under the order number, carrying the new status and an optional note, with a key that has write access. The order moves by the same rules as the panel: a new order is confirmed or cancelled, a confirmed one is prepared, shipped or cancelled, a shipped one is delivered or returned. A move that is not allowed is refused with status 409. The change fires the same notifications a change from the panel fires.
Also asked as: «اغير حالة الطلب من السيستم بتاعي» · «تحديث حالة الطلب api» · «update order status via api»
The address and authentication
POST https://app.arabybot.com/store_api/v1/orders/{number}/status Send the store key in the header Authorization: Bearer abst_… or X-Api-Key. This address changes data, so it needs a key with write access; a read key is refused with status 403. You create the key in the store settings.
The fields
status(required) The new status: new, confirmed, preparing, shipped, delivered, returned or cancelled.note(optional) A note of up to 200 characters, written in the order's log with the key's name.
An example request
cURL
curl -X POST https://app.arabybot.com/store_api/v1/orders/1042/status \
-H "Authorization: Bearer abst_YOUR_WRITE_KEY" \
-H "Content-Type: application/json" \
-d '{ "status": "shipped", "note": "Handed to the courier" }' PHP
$ch = curl_init('https://app.arabybot.com/store_api/v1/orders/1042/status');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer abst_YOUR_WRITE_KEY', 'Content-Type: application/json'],
CURLOPT_POSTFIELDS => json_encode([
'status' => 'shipped',
'note' => 'Handed to the courier',
]),
]);
$answer = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch); Python
import requests
r = requests.post(
'https://app.arabybot.com/store_api/v1/orders/1042/status',
headers={
"Authorization": "Bearer abst_YOUR_WRITE_KEY",
},
json={
"status": "shipped",
"note": "Handed to the courier",
},
timeout=30,
)
print(r.status_code, r.json()) Node.js
// Node.js 18+
const r = await fetch('https://app.arabybot.com/store_api/v1/orders/1042/status', {
method: 'POST',
headers: {"Authorization": "Bearer abst_YOUR_WRITE_KEY", "Content-Type": "application/json"},
body: JSON.stringify({
"status": "shipped",
"note": "Handed to the courier"
}),
});
console.log(r.status, await r.json());
The response
200
{ "ok": true, "order": { "id": 9041, "number": "1042", "status": "shipped", "…": "…" } } - From
newto confirmed or cancelled. - From
confirmedto preparing, shipped or cancelled; and frompreparingto shipped or cancelled. - From
shippedto delivered or returned; and fromdeliveredto returned. - From
cancelledto new only; andreturnedis a final status. - Sending the same current status changes nothing and returns the order as it is.
The refusals
Every refusal comes back as JSON with "ok": false and the code in error:
- 403
read_only_key: The key can read only; create a key with write access in the store settings. - 409
transition_not_allowed: The move from the current status to the requested one is not allowed. - 409
out_of_stock / stock_back_gone: The stock does not allow this move. - 422
bad_status: The status written is not one of the seven. - 404
not_found: No order with this number in this store. - 401
unauthorized: The key is missing, wrong or revoked. - 402
store_plan_closed: The store plan has ended; renew it. - 429: More than 120 requests in a minute.
- 500
server_error: A failure on our side; try again.
The limits
120 requests a minute from one IP address; passing that returns status 429. A store can have up to five keys. A key sees only its own store, and the store's plan must be active.
All store API addresses · All APIs for developers
Frequently asked questions
Does the customer get a notification when I change the status from the API?
A change from the API follows the same rules as the panel and fires the same notifications, the store's webhooks to your systems among them. It is written in the activity log under the key's name.
Why was the status change refused with transition_not_allowed?
Because the move is not an allowed one: such as delivering an order that was not shipped, or changing a returned order. See the allowed moves on this page.
Read next
Try the agent before you pay anything
The agent that will answer your customers is the one answering you now: ask it from the chat button here or on WhatsApp. Your account is free with no credit card, and the free trial on your own number or page is activated after you contact our team on customer-service WhatsApp.