What status should new orders arrive in?

Lesson 10 of 24 7 min read

Choose the Unleashed status for each order, use your account's own custom statuses correctly, and avoid the most common status error.

The status an order lands in decides what your team does next. Placed orders are ready to pick; Parked orders wait for someone to check them. This lesson helps you decide which orders should arrive in which status, and shows you the difference between Unleashed's fixed statuses and your account's own custom ones, which is where most status errors come from.

Two kinds of status

Unleashed sales orders have two separate status fields:

Order status. Unleashed has exactly five fixed values: Parked, Placed, Backordered, Completed and Deleted.
Custom order status. Each account can define up to ten statuses of its own, such as Picking or Awaiting Pick. These are held in a separate field.

Never put a custom status in defaultOrderStatus

defaultOrderStatus and orderStatusMap only accept the five fixed values. A custom status such as Picking there is rejected by Unleashed, and Unleashed's message does not say which field was wrong. Custom statuses belong in customStatusTagMap.

The decision: which fixed status?

defaultOrderStatus	The status for every order that no rule catches. If you leave it unset, paid orders are created as Placed and all others as Parked. Set it when you want one status regardless of payment.
orderStatusMap	A prioritised list of rules. Each rule matches a tag, a source Integration (integrationKey), or both, and sets a status. First match wins, and the list takes priority over defaultOrderStatus.

When to use which

One channel, simple rules: leave defaultOrderStatus unset and let payment decide. Paid orders go straight to Placed; unpaid orders wait as Parked.
Everything should wait for review: set defaultOrderStatus to Parked.
Different channels behave differently: use orderStatusMap with an integrationKey rule per store, and defaultOrderStatus as the fallback.
Specific orders behave differently: use orderStatusMap with tag rules, for example orders tagged as wholesale.

"orderStatusMap": [
  { "tag": "wholesale", "orderStatus": "Parked" },
  { "integrationKey": "hilltop-shopify", "orderStatus": "Placed" }
],
"defaultOrderStatus": "Parked"

Because the first match wins, put the most specific rules first. Here, a wholesale order from the Shopify store is Parked, because the wholesale rule is checked before the store rule.

Your own statuses

customStatusTagMap	Maps order tags to one of your account's custom statuses, with an optional default. This writes Unleashed's separate custom status field.

Remember that Unleashed only allows a custom status on a Parked order. If you set a custom status, the order's fixed status needs to be Parked.

Catching mistakes before they reach Unleashed

validateOrderStatuses	On by default. Before sending, checks the order's status against the statuses your account actually has, and fails with a message naming the valid ones. Also spots a custom status put in defaultOrderStatus, and reports a retired custom status as obsolete rather than unknown.

Leave this on. It never costs you an order Unleashed would have accepted: Unleashed refuses the same orders, but with messages like Invalid status transition. Destination status doesn't exist. that do not name the wrong value. The check refuses them earlier and tells you exactly what to fix. If Supply Lens cannot read your statuses, for example because the endpoint is down, the check is skipped and the order is sent as normal. It costs one call per run, and you can turn it off to save that call.

Afterwards: completing and deleting

completeFulfilledOrders and deleteCancelledOrders, both on by default, decide whether Supply Lens completes fulfilled orders and deletes cancelled ones. You met them in the previous module.

Hilltop's status rules

Hilltop wants paid consumer orders ready to pick, café orders checked first, and café orders flagged with its custom status Credit Check. Priya writes:

orderStatusMap: a rule for the café tag setting Parked.
customStatusTagMap: the café tag mapped to Credit Check.
defaultOrderStatus left unset, so paid consumer orders go to Placed and anything unpaid to Parked.

Her first attempt put Credit Check in defaultOrderStatus. With validation on, the test order failed immediately with a message naming the valid statuses, rather than an unexplained Unleashed rejection.

Recap

Fixed statuses (Parked, Placed, Backordered, Completed, Deleted) go in defaultOrderStatus and orderStatusMap.
Your account's custom statuses go in customStatusTagMap, and only on Parked orders.
With no default, paid orders arrive Placed and the rest Parked.
orderStatusMap rules are checked in order and override the default; put specific rules first.
Keep validateOrderStatuses on for clear error messages.

Quick guides for this topic

How do I add Unleashed?

Complete and continue

Your progress is saved in this browser. Create a free account to keep it everywhere, take quizzes and earn certificates.

Import orders out of Unleashed How should orders be numbered and labelled?