# How automatic actions work

Automatic actions in Ritevo: trigger, conditions and steps, run order, loop protection and the run audit.

An automatic action is a rule: **when something happens and the conditions are met, Ritevo carries out the steps you set**. Everything an action does you can also do by hand - the action simply does it for you.

> **Good to know:** Without an action that is created and turned on, nothing happens on its own. Ritevo has no hidden automation.

## Two kinds of actions

You create actions separately for orders and for messages. They work the same way and differ in what they react to and what they can do:

- [Order actions](https://ritevo.com/en/docs/automations/order-actions) - react to changes in an order and can change its status, issue a document, create a shipment, print a label, update order data and much more.
- [Message actions](https://ritevo.com/en/docs/automations/message-actions) - react to customer messages and can reply for you, also with the help of AI, assign the thread to a user, set a status and much more.

## What an action is made of

- **Trigger** - the one event that starts the action, for example **Order status changed** or **New thread**. Every action has exactly one trigger.
- **Conditions** - optional. They narrow the action down, for example to paid orders only or to messages from the customer only. You can add up to 50 conditions.
- **Steps** - what Ritevo should do. At least one, at most 50. They run in order. In the form these are the **Action #1**, **Action #2** and further cards, added with the **Add step** button.
- **Run time zone** - conditions with a time of day or a day of the week are counted in it.
- **Active / Inactive** - only active actions run. An inactive action stays saved but does nothing.

You set everything in one form: basic settings at the top, conditions on the left, steps on the right.

![An empty new-action form: name and description, trigger, run time zone, the Active switch, a condition card and a step card](https://ritevo.com/docs/automations/en-action-form-empty.webp)

## How Ritevo runs an action

1. Something that is a trigger happens - no matter whether you made the change, it came from the sales channel, or another action made it.
2. Ritevo takes all active actions with that trigger.
3. For each of them it checks the conditions. If one is not met, that action does not run.
4. It carries out the steps in order. The next step starts only after the previous one succeeded.
5. Every run is saved in the audit.

If several actions match one event, **all of them run**. Actions have no priority and no set order, so do not build actions that depend on which one fires first.

When order matters, you have two ways - pick the one you prefer:

- **One action with several steps.** Steps always run in order, and the next one starts only after the previous one succeeded. This is the simplest and most reliable way.
- **A chain of actions.** The last step of action A is the trigger of action B - for example A ends with the **Create shipment** step and B has the **Shipment created** trigger. It is useful when you want the second part kept apart: with its own conditions, or so you can turn it off independently of the first.

## How conditions work

- All conditions of an action have to be met **at the same time**. There is no "or" between conditions.
- Inside one condition you can pick several values - then **any of them** is enough. For example in the **Integration is** condition you pick one or several from the list of your integrations: eBay and WooCommerce means "an order from eBay or from WooCommerce".
- A range is set with two conditions: **from** and **to**. Working hours, for example, are **Action run time from** 08:00 and **Action run time to** 16:00.
- Times of day and days of the week are counted in the **time zone set in the action**. The time in the form, however, is entered in your computer's time. So leave the action on the zone the form sets by itself - your own. Then **Action run time from** 08:00 simply means 8:00 where you are, also when the customer is in another country. If you change the action's zone to one different from yours, the time you entered shifts by the difference between the zones. Daylight saving time is handled automatically.
- A range that crosses midnight (for example 22:00-05:00) needs **two actions**: one with the condition **from** 22:00 and another with the condition **to** 05:00. The form lets you set both conditions in one action, but such an action will never run - every condition is checked on its own, and no time of day is both after 22:00 and before 05:00.

## Branches inside a step

A step can have branches, that is several variants with their own conditions. It is useful when the same action should do something different depending on the order or message.

- Ritevo checks the variants in order and runs the **first** one whose conditions are met.
- If no variant matches, it runs the step's default action.
- If the step has no default action, the whole action stops and the audit shows **Action stopped by conditions**.
- Branches have one level - a variant holds a single operation, not further steps.

## Loop protection

An action changes data, and a data change can be a trigger. Ritevo makes sure actions do not keep setting each other off forever - in three ways:

1. **An action never triggers itself.** If an action with the **Order status changed** trigger changes the status itself, it will not start a second time because of that.
2. **Actions can trigger other actions, but not in a circle.** The last step of action A can start action B, and that one action C. But when saving or turning on an action would close a circle (A starts B, B starts A - also through more actions), Ritevo will not save it and shows an error about a detected infinite cycle. Only active actions count.
3. **A safety switch at run time.** If actions still run on the same order or thread too many times in a short period, Ritevo pauses them. The orders or messages audit then shows an **Infinite loop detected** entry together with the action and the step it happened on. Your manual changes are never blocked this way.

> **Good to know:** While an action is going through its steps, its changes **do not start any new action** - the following steps only move the same action forward. A new action can be started only by an event from outside an action (a trigger) or by the **last step** of another action.

## Run audit

Every run of an action is saved in the audit: **Settings → Audit**, separately for orders and for messages. You can filter entries by action and by result. Possible results:

- **Action continues** - a step ran and there are more.
- **Action finished** - the last step ran.
- **Action stopped by conditions** - in a step with branches no variant matched.
- **Infinite loop detected** - the safety switch kicked in.
- **Error** - a step failed, for example an integration rejected the request. The entry holds the error description. In order actions, after an error in a step that uses an integration - shipment, sending a document to accounting, printing - the action continues: [Steps that wait for an external system](https://ritevo.com/en/docs/automations/order-actions#waiting-steps). After an error in any other step, the remaining steps of that action do not run.

## What actions do not do

- They do not start at a set time. There is no "every day at 8:00" trigger - time exists only as a condition.
- They do not wait. There is no "wait an hour" or "send after 2 days" step.
- They cannot be run by hand on a chosen order or thread. You can only turn an action on or off.
- One action has one trigger. For two events create two actions.
- Limits: up to 1000 actions per company, up to 50 steps and 50 conditions per action.

## Saving an action through the API (for AI and integrators)

This section exists only in the Markdown version. On the detailed pages, the names of triggers, conditions and steps are followed in brackets by their API names and the field the value goes in. Order actions are saved with `POST /orders/automatic-actions`, message actions with `POST /messages/automatic-actions`; a change is `PATCH /{id}`, turning on and off `PATCH /{id}/toggle-active`, deleting `DELETE /{id}`. The API base address is `https://api.ritevo.com/api`. The full definition of every endpoint and field: [Swagger UI](https://api.ritevo.com/api/webjars/swagger-ui/index.html), machine-readable (OpenAPI) at `https://api.ritevo.com/api/v1/api-docs`. The paths given next to values (for example `GET /integrations/shippings`) are relative to the base address.

- Action fields: `name` and `description` (both required, up to 255 characters), `active`, `userTimezone` (required, an IANA zone name, for example `Europe/London`), `triggerType` (exactly one), `conditions` (0-50), `actionSteps` (1-50).
- Step: `stepOrder` numbered from 1 with no gaps or repeats, and `action` or `conditionalBranches` (or both - then `action` is the default action). Variant: `branchOrder` from 1, `conditions` (at least one) and `action`.
- Condition: `type` and **exactly the value field** given next to its name. Do not send the other fields.
- Step operation (`action`): `type` and the value field given next to the step's name.
- Time and date: `offsetDateTimeValue` is a full date-time with an offset, for example `2026-01-10T08:00:00+00:00`. For time-of-day conditions (`*_TIME_FROM`, `*_TIME_TO`) only the hour and minute read in `userTimezone` count, so give the time with that zone's offset; the date can be anything. For date conditions (`*_DATE_FROM`, `*_DATE_TO`) the whole instant counts.
- Days of the week: `integerValues` with numbers 1-7, where 1 is Monday and 7 is Sunday.
- Conditions without a value ("has invoice", "from customer"): `booleanValues` with a single `true`. Steps that need a confirmation (deleting): `booleanValue` equal to `true`.
- Get the identifiers of integrations, custom statuses, message templates, users and document settings templates from the API lists - they are UUIDs.
- Saving is rejected with code 409 if active actions would close a circle. The trigger an action fires follows from its **last** step: `UPDATE_STATUS` → `STATUS_CHANGED`, `UPDATE_USER_DEFINED_STATUS` → `USER_DEFINED_STATUS_CHANGED`, `UPDATE_PAYMENT` → `PAYMENT_DATA_CHANGED`, `GENERATE_INVOICE` / `DELETE_INVOICE` → `INVOICE_CHANGED`, `GENERATE_RECEIPT` / `DELETE_RECEIPT` → `RECEIPT_CHANGED`, `TRANSFER_INVOICE_TO_EXTERNAL_ACCOUNTING` → `TRANSFERRED_INVOICE_TO_EXTERNAL_ACCOUNTING`, `CREATE_SHIPMENT` → `CREATE_SHIPMENT`, `PRINT_SHIPMENT_LABEL` / `PRINT_RECEIPT` → `CREATE_PRINT_JOB`, `DELETE_ORDER` / `RESTORE_ORDER` → `ORDER`; for messages `SEND_MESSAGE_TO_THREAD` → `MESSAGE_RESPONSE`, `TEMPLATE_SEND_MESSAGE_TO_THREAD` → `TEMPLATE_MESSAGE_RESPONSE`, `AI_SEND_MESSAGE_TO_THREAD` → `AI_MESSAGE_RESPONSE`, `UPDATE_ASSIGNED_USER` → `ASSIGNED_USER_CHANGED`, `UPDATE_READ_STATUS` → `READ_STATUS_CHANGED`. The rest: `UPDATE_OWN_NOTE` → `OWN_NOTE_CHANGED`, `UPDATE_FAVORITE_STATUS` → `FAVORITE_STATUS_CHANGED`, `UPDATE_ORDER_DATE` → `ORDER_DATE_CHANGED`, `UPDATE_BUYER` → `BUYER_DATA_CHANGED`, `UPDATE_COMPANY` / `USE_BUYER_AS_BILLING_RECIPIENT` → `COMPANY_DATA_CHANGED`, `UPDATE_DELIVERY_ADDRESS` → `DELIVERY_ADDRESS_CHANGED`, `UPDATE_DELIVERY_BASIC` → `DELIVERY_BASIC_CHANGED`, `UPDATE_DELIVERY_METHOD` → `DELIVERY_METHOD_CHANGED`, `UPDATE_DELIVERY_PICKUP_POINT` → `DELIVERY_PICKUP_POINT_CHANGED`, `UPDATE_DELIVERY_TIME` → `DELIVERY_TIME_CHANGED`, `TRANSFER_RECEIPT_TO_EXTERNAL_ACCOUNTING` → `TRANSFERRED_RECEIPT_TO_EXTERNAL_ACCOUNTING`.


---

All help in one file: https://ritevo.com/llms-full.txt. Help map with links to every page: https://ritevo.com/llms.txt.