Creating a state machine

Alongside Shopware’s built-in machines you can create your own — for example to model a subscription lifecycle, a return process or any custom workflow of your own.

Create a new machine

1. Go to Settings → Plugins → State Machine Manager.
2. Click Create state machine at the top right.
3. Fill in:
   • Technical name — the internal identifier, in entity.state format (for example subscription.state). Only lowercase letters, numbers and underscores are allowed. See Naming conventions.
   • Name — the readable display name your team will see.
4. Click Save.

Both fields are required. If the technical name does not follow the entity.state format, an inline error explains what to fix.

After saving you are taken to the machine’s detail view, where you can start adding states and transitions.

Recommended order of work

A new machine starts empty. Building it up in this order avoids validation warnings along the way:

1. Add the states first — every status the process can be in. See Managing states.
2. Pick the initial state — the one an entity starts in. See Managing states.
3. Add the transitions between them — the allowed moves and the action that performs each. See Managing transitions.
4. Arrange the diagram so the flow reads clearly. See The visual editor.
5. Validate to confirm there are no missing pieces. See Validation.

Next steps

• General settings — edit an existing machine’s name and initial state.
• Managing states