Order statuses (built-in and custom)
An order’s status says where it is in your process — waiting for payment, paid and ready to pack, shipped, finished, or undone. TitanCart ships with seven order statuses and sets most of them for you as payments succeed, fail, or are refunded. You can rename them, recolour them, decide which ones e-mail the customer and which ones return stock, and add your own stages in between. All of that lives under Settings → Order Statuses; this article explains what each setting does and which parts of the store key off a status.
Changing the status of one order happens on the order itself, in the Update Status card — see Managing orders section 4. This article is about the statuses themselves.
1. Where statuses live
Open Settings → Order Statuses. The page has two tabs:
- Order Statuses — the statuses an order moves through. This is the tab this article is about.
- Fulfillment Statuses — the stages a shipment can be in (Pending, Picked Up, Packed, Shipped). They label shipments on Sales → Fulfillment and in the customer’s My Account; they do not change the order’s status. See Fulfillment and shipments.
Each row shows the status’s colour, its name, a DEFAULT badge on the one new records start in, a Notifies badge when it e-mails the customer, and a Restores stock badge when it returns items to inventory. Click a row to edit it; use + Add Status to create one.
2. The seven built-in order statuses
These are seeded when TitanCart is installed. The Set by TitanCart when column is what happens without you touching anything; you can always move an order to any status by hand.
| Status | Set by TitanCart when | E-mails the customer | Stock |
|---|---|---|---|
| Pending Payment | Every order starts here the moment it is placed. Card orders usually leave it within a second; it is the default and cannot be deleted. | No | — |
| Processing | The payment is taken — a card charge succeeds, a PayPal or Venmo payment is captured, an authorised card is captured, or a Cash on Delivery order is set to start fulfillment. This is the status the Needs Fulfillment queue watches. | Yes — except the automatic move from Pending Payment to Processing at checkout, which is covered by the order confirmation e-mail instead. | Deducted at payment, not by the status. |
| On Hold | An offline payment (Check, Bank Transfer, Cash on Delivery by default) is awaiting your confirmation; a card is authorised but not yet charged; or an exchange replacement order is waiting for the returned goods. | No | Reserved (card authorisations) or not yet taken (offline methods). |
| Completed | Never automatically — you set it when the order is done. Shipping every item does not complete an order by itself. | Yes | — |
| Cancelled | You click Cancel Order; an authorisation is voided, declined or expires; or Cancel unpaid orders automatically closes a Pending Payment order that was never paid (that one sends no e-mail). | Yes | Restore |
| Refunded | A refund for the full order total is issued. Partial refunds leave the status alone. | Yes | Restore |
| Failed | A gateway declines or cannot verify the payment (Stripe, PayPal, Venmo). | No | — |
The seven are protected. TitanCart’s automatic moves refer to these statuses by their fixed internal handle, so you may rename and recolour them freely but cannot delete them (the Delete button is not offered; from 0.2.69 the request is refused). Before 0.2.69 only the default was protected — if an older store deleted one, a paid order’s gateway has nowhere to move it and the move is logged as failed.
3. What each setting does
Click a status to open its editor. On the Order Statuses tab it has:
- Name — what you, your customers and your e-mails see. Change it whenever you like; the customer’s My Account, the Sales screen and the
{order_status}e-mail token all follow. - Handle — the internal identifier (lower-case letters, digits and underscores). It is filled in from the name when you create a status and cannot be changed afterwards. Automations, webhooks and extensions refer to statuses by handle, which is why renaming is safe and deleting is not.
- Color — the badge colour on the Sales list, the dashboard’s Order Status chart, the Fulfillment queue and the customer’s order pages. Pick a swatch or any colour.
- Inventory — None — no inventory change or Restore — return stock to inventory. Stock is deducted once, when payment is taken; a status set to Restore gives those quantities back the first time an order enters it (Cancelled and Refunded are set to Restore out of the box). Items already sent back through a completed return are not restored twice.
- Notify customer — when on, every move into this status e-mails the customer, whether or not the person changing the status ticks the box on the order. The e-mail itself is the status’s template under Settings → Notifications; see section 7.
- Position — the order of the statuses in every list and dropdown; lower numbers come first. Leave it at 0 when creating a status to add it to the end.
4. Adding your own status
Custom statuses are for stages your process has and the defaults do not — Awaiting Pickup, Engraving, Back-ordered, Partially Shipped.
- On the Order Statuses tab click + Add Status.
- Type the Name; the Handle fills itself in (adjust it now if you want — it is permanent).
- Pick a Color, choose the Inventory behaviour (almost always None), switch Notify customer on if the customer should hear about this stage, and set its Position (or leave 0 for the end of the list).
- Click Create.
The new status is immediately available in the Update Status dropdown on every order, as a filter tab on the Sales list, as a colour badge in the customer’s My Account, in the dashboard’s Order Status chart, in order exports, and as an event (Order status changed to <Name>) under Settings → Notifications.
What a custom status does not do. TitanCart’s built-in behaviour keys off the seven original handles, so a custom status is a label for your team and your customer, not a trigger:
- It does not put orders in the Needs Fulfillment queue — only Processing does. Create the shipment while the order is Processing, then move it to your custom stage.
- It does not count as “paid” for the things that unlock on payment: digital download links, subscription activation, lottery tickets, verified-purchase review badges and return eligibility all look for Processing or Completed.
- It does count towards Revenue Reports: reports exclude Cancelled, Refunded and Failed and include everything else. If you create a “Declined” or “Fraud” stage, use the built-in Cancelled or Failed instead so the figures stay right.
- Its e-mail is the generic Order status changed: other statuses template unless you give it one of its own (section 7).
5. Which parts of the store read a status
| Feature | Statuses it looks for |
|---|---|
| Needs Fulfillment queue (Sales → Fulfillment) | Processing, with physical items still to ship |
| Revenue Reports and the dashboard figures | Everything except Cancelled, Refunded and Failed |
| Digital downloads | Links issued at Processing or Completed; revoked at Cancelled or Refunded |
| Product reviews — Verified purchase badge | Completed |
| Returns (RMA) — “Request a return” shown | Completed, within the return window |
| Subscriptions, Lottery, Software Licensing extensions — treat the order as paid | Processing or Completed; Lottery also voids tickets at Cancelled or Refunded |
| Best Sellers ranking | Counts every order; subtracts at Cancelled or Refunded |
| API webhooks | order.status_changed on every change; order.completed and order.cancelled on those two |
| Cancel unpaid orders automatically (Settings → General Settings) | Pending Payment with no completed payment after the set hours |
6. Renaming, reordering and deleting
- Rename any status, including the built-ins — the handle stays, so nothing breaks. “Pending Payment” can become “Awaiting payment”, “Completed” can become “Delivered”.
- Reorder with Position; lower numbers come first.
- Delete with the Delete button on the row — offered for your own statuses only. A status that orders (or, on the Fulfillment tab, shipments) still use is refused with the count; filter the Sales list by it and move those orders first. Stores older than 0.2.69 did not check this: an order left on a deleted status shows a blank badge and drops out of the Fulfillment queue.
7. Statuses and e-mails
Two switches have to agree for a status change to e-mail the customer: the status’s Notify customer setting here (or the Notify customer via email tick on the order), and the status’s event switch under Settings → Notifications, where each of the seven built-ins has its own customer template (Order status changed: Processing, and so on) and every other status shares Order status changed: other statuses. The admin copy of a status e-mail is controlled only on the Notifications page and is off by default. E-mail notifications and templates section 4 has the details and the placeholders.
What order statuses do — and don’t
Statuses describe an order and drive a small set of behaviours: the Restore inventory action, the Notify customer e-mail, the Fulfillment queue (Processing), the revenue figures (anything not Cancelled / Refunded / Failed) and the paid-order checks (Processing / Completed). They do not take or refund money — moving an order to Refunded by hand records nothing at the gateway; use the Refund button on the order. They do not create shipments, and shipping everything does not move an order to Completed. Custom statuses are labels: visible everywhere, triggers nowhere.
Troubleshooting
- I moved an order to my custom status and it vanished from Needs Fulfillment. Expected — the queue lists Processing orders only. Create the shipment first, or leave the order in Processing until it has shipped.
- Revenue Reports include orders I consider dead. Only Cancelled, Refunded and Failed are excluded. Move those orders to one of the three, or use them instead of a custom “declined” stage.
- The customer was e-mailed about a status I did not tick Notify for. The status has Notify customer switched on here, which sends regardless of the tick on the order. Switch it off on the status.
- The customer was not e-mailed although Notify customer is on. Check the status’s event switch under Settings → Notifications and that its template is not set to Disabled. The move from Pending Payment to Processing at checkout never sends a status e-mail by design; the order confirmation covers it.
- I renamed a status but the thank-you page still shows the old wording. Before TitanCart 0.2.69 the order-received page after checkout used its own fixed labels and colours and showed a custom status by its handle; from 0.2.69 it uses your name and colour like everywhere else.
- Stock did not come back when I moved an order to my custom “Returned” status. Set that status’s Inventory to Restore. Stock is only returned once per order, and only if it was deducted in the first place (an unpaid order has nothing to give back).
- An order shows a blank status badge. Its status was deleted (possible before 0.2.69). Open the order and set a new status from the Update Status card.
See also
- Managing orders (the Sales screen) — changing a single order’s status, notes, refunds and cancellation.
- Fulfillment and shipments — the Needs Fulfillment queue and the Fulfillment Statuses tab.
- Refunds and cancellations — what Refunded and Cancelled do to money, stock and e-mails.
- E-mail notifications and templates — the per-status e-mails and their switches.
- Inventory & stock control — when stock is deducted and how to adjust it by hand.