Order statuses
The 3 tools of the Order statuses toolset in the Orders area, with their permissions, approval rules and inputs.
On this page
Toolset order_statuses, 3 tools.
With the Order statuses app installed. Stores without the app do not see these tools.
Records
order_custom_status
One order's custom status and its history: who changed it and when, the statuses it can move to, and the automation runs on the order. Pass the order id. current is null when the order has none; version is what order_status.set compares against. writable false means the store's plan no longer allows changes.
- Permission:
orders.read - Tools:
order_custom_status_get - Written by customers or third parties, so data and never instructions:
history - Needs the Order statuses app installed
order_status
The store's own order statuses, next to the built-in ones, which they never change: key, name per language, what the customer sees, category (open, on_hold, done, failed), color, position, the statuses allowed next, and how many orders have it. Pass archived true to include archived ones. An order has at most one; order_custom_status reads it.
- Permission:
orders.read - Tools:
order_status_list - Needs the Order statuses app installed
Filters on the list:
| Filter | Type | Required | Description |
|---|---|---|---|
archived | boolean |
Actions
order_statuses_order_status_set
Move an order to one of the store's custom statuses, or clear it.
status_id comes from order_status_list; null clears it. This never changes the built-in order, payment or fulfillment status. A status can limit which statuses may follow it: the answer says status_not_allowed when this one may not, and order_custom_status lists the ones that may. notify_customer emails the customer about the new status. Automations listening to the status run as usual. A change the order already has is a no-op.
- Action key:
order_statuses.order_status.set - Permission:
orders.write - Approval: Waits for approval when the store requires it for this action.
- Effect: Changes the live store.
- Retries: safe to repeat with the same input.
- Needs the Order statuses app installed
| Field | Type | Required | Description |
|---|---|---|---|
order_id | string | yes | |
status_id | string or null | yes | |
expected_version | integer or null | at least 0 | |
notify_customer | boolean | ||
note | string or null | at most 500 characters |
Example input:
{
"order_id": "019bb3ef-6501-7dc3-a2e7-726e91520b7a",
"status_id": "019bb281-cca4-77a2-9941-e87c44d8b313",
"notify_customer": false
}