Purchase and work order statuses

Reference

A purchase or work order moves from Draft, through the tenant's confirmation and the merchant's acceptance, to Completed — or ends Cancelled. An order whose funds hold times out becomes Expired and can be brought back.

Overview#

Purchase orders and work orders share one set of statuses. Each move between statuses is checked on the server: an action offered in the wrong status is refused, whatever the screen showed. The order is a handshake — the tenant confirms it, the merchant accepts it — recorded on the order as Confirmed (tenant) and Confirmed (merchant). The detail page offers each user only the actions that fit the order's status and their role. The rules below are those of a purchase order; work orders differ in a few places, listed under Work orders.

Statuses#

Refuel orders use the same status list plus statuses of their own — Funds Held, Authorized, Awaiting Invoice and Blocked. A purchase order never takes those.

The purchase order lifecycle:

stateDiagram-v2
    state "Pending Tenant Confirmation" as Approval
    state "In progress" as Working
    [*] --> Draft: created
    [*] --> Approval: Driver App, approval required
    Approval --> Pending: supervisor approves
    Approval --> Cancelled: supervisor rejects or driver cancels
    Draft --> Pending: tenant confirms
    Draft --> Cancelled: driver cancels
    Pending --> Working: merchant accepts
    Pending --> Cancelled: tenant cancels or merchant rejects
    Working --> Completed: merchant marks fulfilled
    Draft --> Expired: hold times out
    Pending --> Expired: hold times out
    Working --> Expired: hold times out
    Expired --> Draft: re-confirm
    Expired --> Pending: re-confirm
    Expired --> Working: re-confirm
    Completed --> [*]
    Cancelled --> [*]

Rules#

Confirming (Draft → Pending)

• The order needs at least one line item, every quantity must be 1 or more, and every price must still match the store's current price list.
• All checks run together: if any line fails, nothing changes and the order stays Draft.
• On success the order becomes Pending and Confirmed (tenant) is set. Who is notified: Who sees and is notified about an order.
• The tenant must still be able to cover the order total; otherwise confirmation is refused. See Order funds holds and expiry.

Supervisor approval (Pending Tenant Confirmation)

• Approving sends the order straight on to Pending. The same checks as a tenant confirmation apply, and the supervisor is recorded under Confirmed (supervisor).
• Rejecting cancels the order. The web form asks for a Rejection reason, which is kept in the order's audit log.
• Approve and Reject are on the web detail page of a purchase order.
• An order waiting here cannot be confirmed any other way, and it is never moved to Expired: if its hold times out, the money goes back but the order keeps waiting for the decision.

Merchant actions

• Accepting a Pending order sets Confirmed (merchant) and moves it to In progress; rejecting it cancels it.
• The tenant must be able to cover the order when the merchant accepts it; if not, the acceptance is refused and the order stays Pending.
• Marking an In progress purchase order fulfilled moves it to Completed and records the charge to the tenant. If the charge cannot be made, the order stays In progress; see Order-to-cash flow.
• When two merchant users act on the same order at once, the first action wins and the second is told the status has already changed.
• On the web, the merchant's purchase order list does not show Draft orders.

Cancelling

• On the web, the tenant can cancel a purchase order only while it is Pending.
• In the Driver App, a driver can cancel their own purchase order while it is Draft, Pending Tenant Confirmation or Pending.
• Cancelling or rejecting a Pending or Pending Tenant Confirmation order releases the money held for it at once.

Expiry and re-confirmation

• A purchase order reserves funds from the tenant's wallet as soon as it is created; a work order does so once its cost is known. The hold lasts six hours by default. A tenant paying on a credit line holds no funds, so its orders never expire.
• When a hold times out, an order in Draft, Pending or In progress becomes Expired and a notification is sent. Expiry never cancels an order.
• Re-confirm places a new hold for the same amount on the same wallet and returns the order to exactly the status it had.
• Re-confirm is refused, and the order stays Expired, if the wallet can no longer cover the amount or if the wallet the money was held on is no longer the tenant's active wallet.
• Re-confirm is on the web detail page of purchase and work orders for tenant users, and in the Driver App for drivers. Merchants cannot re-confirm, because it spends the tenant's money.

Step by step: Re-confirm an expired order.

Work orders

Work orders follow the same main path — confirmed by the tenant, accepted by the merchant, then completed — with these differences:

• A work order can be cancelled in any status except Completed, and the merchant can reject a Pending one in the Merchant App.
• A work order cannot be completed until it has a cost.
• The supervisor decision on a work order in Pending Tenant Confirmation is not offered on the web.
• On the web, a work order's status is a field on its edit form.

See Work orders.

Permissions#

Who can move a purchase order on. Each action appears only for these roles, and only while the order is in the matching status.

Tenant Accountants and Merchant Accountants can view orders but take none of these actions. A merchant supervisor acts only on orders for the stores they are assigned to.

Edge cases#

• A supervisor approval that fails the confirmation checks — a stale price, for example — leaves the order in Pending Tenant Confirmation.
• An order completed or cancelled before its hold times out is never moved to Expired.

Related#

• Purchase orders
• Work orders
• Order funds holds and expiry
• Who sees and is notified about an order
• Confirm or cancel a purchase order
• Accept, reject or fulfil a purchase order
• Approve or reject a purchase order as a supervisor
• Re-confirm an expired order