A state machine is a way of describing something that can only be in one situation at a time, called a state, and that moves from one state to another only when a specific event happens. A traffic light is the classic example. It is red, green or amber, never two at once, and it changes in a fixed order.

It concerns anyone who builds or commissions software, and anyone who runs an online store, because orders, payments, subscriptions and returns all behave like state machines. Understanding the idea helps you spot bugs such as an unpaid order being shipped or a refund being sent twice, and helps you brief developers clearly.

What is a state machine?

The full name is finite-state machine, because the list of possible states is finite and known in advance. A state machine has five building blocks.

  • States: the possible situations, such as pending, paid, shipped, delivered, canceled and refunded for an order.
  • Initial state: where everything starts, for example pending when a customer places an order.
  • Events: what happens from outside, such as "payment succeeded", "label printed" or "customer requested a refund".
  • Transitions: the allowed moves from one state to another in response to an event. Paid can move to shipped. Shipped cannot move back to pending.
  • Final states: where the life cycle ends, such as delivered, canceled or refunded.

Two more ideas often appear.

  • Guards are conditions that must be true for a transition to happen. An order can move to shipped only if all items are in stock.
  • Actions are things that happen during a transition, such as sending a confirmation email when an order becomes paid.

A state machine is a way of thinking, independent of any technology. You can draw it on paper, write it in any programming language or run it with dedicated tools. It also differs from a simple status field. A status field just stores a value. A state machine also defines which changes are allowed and which are forbidden.

Why it matters

Without clear states and rules, software ends up in situations that should never happen. In a store, those situations cost money.

Imagine a store processing 3,000 orders a month with an average order of $55. Its order code updates the status from several places, the checkout, the payment webhook, the warehouse tool and the support dashboard, with no rules on which changes are allowed. Once in a while, a delayed payment notification arrives after the order was canceled, and the order switches back to paid and gets shipped. If that happens to 0.5% of orders, that's 15 shipped orders a month without valid payment, about $825 of goods plus shipping, every month.

With a state machine, the rule is explicit. A canceled order is a final state and no event can move it to paid. The late notification is logged and ignored, or triggers a refund. The same logic prevents double refunds, shipping before payment and subscriptions that renew after being canceled.

How it works

You can design a state machine for any process in a few steps.

  • List the states. Write every situation the thing can be in. Keep names short and unambiguous.
  • Pick the initial state. Decide where every new item starts.
  • List the events. Note everything that can happen, from customers, staff, payment providers or carriers.
  • Draw the transitions. For each state, write which events are allowed and which state they lead to. Everything not listed is forbidden.
  • Add guards and actions. Specify conditions, such as stock available, and side effects, such as emails, stock updates or invoices.
  • Handle the unexpected. Decide what happens when a forbidden event arrives, for example log it, alert someone or refund automatically.
  • Implement and test. Developers can code it directly or use libraries such as XState for JavaScript, or workflow services like AWS Step Functions.

A typical order flow looks like this:

  1. Pending, when the order is created at checkout.
  2. Paid, when the payment provider confirms the payment.
  3. Fulfilled or shipped, when the parcel leaves or the digital product is delivered.
  4. Delivered, when the carrier confirms delivery.
  5. Canceled or refunded, as alternative endings from the allowed states.

Benchmarks and examples

  • Payments: Stripe's PaymentIntent object moves through states such as requires_payment_method, requires_action, processing, succeeded and canceled. Your store reacts to each change through webhooks.
  • Orders: almost every ecommerce platform models orders with states like pending, paid, fulfilled, refunded and canceled, and order tracking exposes the shipping part to customers.
  • Subscriptions: trialing, active, past due, paused and canceled.
  • Returns: requested, approved, received, inspected, refunded or rejected.
  • Everyday objects: traffic lights, vending machines, elevators and turnstiles are all state machines.
  • Size: most business processes need between 5 and 12 states. More than that often means two processes are mixed together, such as payment and shipping, and should be split.

Common mistakes

  • Updating status from everywhere. When several parts of the code set the status freely, invalid jumps become possible. Route every change through the same rules.
  • Ignoring event order. Payment and carrier notifications can arrive late or twice. Handle duplicates and out-of-order events.
  • Mixing independent processes. Combining payment status and shipping status into one field creates states like "paid and shipped and partially refunded" that are hard to manage.
  • Forgetting the unhappy paths. Cancellations, failed payments, lost parcels and partial refunds need states too.
  • Not documenting it. If the diagram lives only in a developer's head, support and operations can't understand why an order is stuck.

Best practices

  • Draw it first. A simple diagram with boxes and arrows, reviewed by the business team, catches most design errors.
  • Make forbidden moves explicit. Every state should list allowed transitions, and anything else is rejected.
  • Separate payment, fulfillment and returns. Give each its own state machine and link them through events.
  • Log every transition. Store who or what triggered each change and when. It makes support and audits easy.
  • Make event handling idempotent. Processing the same webhook twice should not change the result.
  • Show states to customers in plain words. "Preparing your order" and "On its way" are clearer than internal codes.

In Roctify

You don't need to design a state machine to sell on Roctify. Each order follows its life cycle automatically. It is created at checkout, recorded as paid when Stripe or PayPal confirm the payment, or handled as cash on delivery, and digital products are delivered automatically after payment. Your orders and customers are shared by your link-in-bio page and your storefront, so an order has one status everywhere.

FAQ

What is a state machine in simple terms?

It is a model where something can only be in one of a few known situations at a time and moves between them following fixed rules. A traffic light or an online order are good examples. The rules say which moves are allowed and which are forbidden.

Why are state machines useful in ecommerce?

Orders, payments, subscriptions and returns all go through clear stages. A state machine makes sure they move only in allowed ways, which prevents costly errors such as shipping an unpaid order, refunding twice or renewing a canceled subscription.

What is the difference between a state machine and a workflow?

A workflow describes a sequence of tasks, often involving people, such as approving a return then refunding it. A state machine describes the possible states of one thing and the allowed transitions between them. Many workflow tools use state machines underneath to track where each item is.