Naming conventions
The module enforces a few simple naming rules so that machines, states and actions stay consistent and work reliably with the rest of Shopware.
State machine technical name
Section titled “State machine technical name”Format: entity.state — a lowercase entity name, a dot, then state.
- Only lowercase letters, numbers and underscores, with a single dot separating the two parts.
- Examples:
order.state,subscription.state,return_request.state.
This is the identifier Shopware and other plugins use to find the machine, so it must be exact. On core state machines it is locked and cannot be changed.
The readable Name has no format restrictions — use whatever is clearest for your team.
State technical name
Section titled “State technical name”- Must start with a lowercase letter.
- May contain only lowercase letters, numbers and underscores (
snake_case). - Examples:
open,in_progress,partially_paid.
Technical names must be unique within a machine; trying to reuse one is blocked with an inline error. The state’s Name is free-form.
Transition action name
Section titled “Transition action name”- Written in the same lowercase, underscore style (
snake_case). - The action name is what triggers the move, so pick verbs that read naturally:
process,complete,cancel,refund.
Within one machine you can reuse an action name for different state pairs, and you can have several actions between the same two states — only an exact match of action, source and target counts as a duplicate.
A note on display names
Section titled “A note on display names”Everywhere the module shows a state or transition, it prefers the readable Name and falls back to the technical name when no name is set. Giving every state a clear name keeps the lists and the diagram easy to read.