> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.solvimon.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.solvimon.com/_mcp/server.

# Workflow triggers

A workflow trigger is the record Solvimon creates each time a workflow matches an event. Triggers are how you prove a workflow ran, and how you run one on demand.

---

## How it works

Workflows and actions are configuration and live in the Configuration API. Triggers are transactional records and live in the [Transaction API](https://docs.solvimon.com/api-docs/transaction-api/workflow-triggers/get-workflow-triggers). Each trigger names the workflow that ran, the customer it ran for, and a type-specific block pointing at the invoice, payment, subscription or wallet involved.

| Trigger type | Created by                                                        |
| ------------ | ----------------------------------------------------------------- |
| `EVENT`      | Solvimon, from a lifecycle event that matched an active workflow. |
| `MANUAL`     | You, through the API or Desk, usually to test or to re-send.      |

The type-specific block matches the workflow's `type`:

| Workflow type               | Block                       | Key field                      |
| --------------------------- | --------------------------- | ------------------------------ |
| `INVOICE`                   | `invoice`                   | `invoice_id`                   |
| `PAYMENT`                   | `payment`                   | `payment_id`                   |
| `PRICING_PLAN_SUBSCRIPTION` | `pricing_plan_subscription` | `pricing_plan_subscription_id` |
| `WALLET`                    | `wallet`                    | `wallet_id`, `wallet_type_id`  |
| `USAGE`                     | `usage`                     | `meter_value_calculation_id`   |

A `USAGE` workflow produces an `EVENT` trigger when a customer's consumption crosses a threshold of their [usage limit](/platform-guides/meter-and-event-design/usage-limits), once per threshold per billing period. Its `usage.event` block names the customer that crossed, the threshold and its `threshold_type`, and the resolved limit the threshold came from.

## Implementation

### Trigger a workflow manually

Creating a trigger runs the workflow's active actions immediately. This is the fastest way to verify an email before you widen a workflow's customer scope:

**`Manually trigger an invoice workflow`**

```bash Manually trigger an invoice workflow
curl -X POST https://test.api.solvimon.com/v1/workflow-triggers \
  -H "X-API-KEY: <apiKey>" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "MANUAL",
    "workflow_id": "wf_7KcQm1RtbXeUvL2NpHZ4S",
    "customer_id": "cust_AbD3DqausjOYiMNDZY11F",
    "invoice": {
      "invoice_id": "inv_6WdKp3ZqtYcRnB8MjXH2V"
    }
  }'
```

**`Response`**

```json Response
{
  "object_type": "WORKFLOW_TRIGGER",
  "id": "wft_8LmPc5XrvNbTeK4QjYZ9H",
  "type": "MANUAL",
  "workflow_id": "wf_7KcQm1RtbXeUvL2NpHZ4S",
  "customer_id": "cust_AbD3DqausjOYiMNDZY11F",
  "invoice": {
    "invoice_id": "inv_6WdKp3ZqtYcRnB8MjXH2V"
  }
}
```

For a payment workflow, swap the block for `"payment": { "payment_id": "pay_..." }`. Wallet triggers are `EVENT`-only in practice, since the balance condition is evaluated by Solvimon.

### Read the balance a wallet trigger fired on

A wallet trigger records the balance that crossed the threshold, so you can answer "how low was it?" without reconstructing the wallet at that moment. `wallet_balance.open_balance` is the open balance when the execution was created and `wallet_balance.threshold` is the threshold configured on the workflow it crossed. Both are stated in the unit the wallet's ledger is denominated in, so each is a container carrying `credits` and `amount` of which exactly one is populated:

**`A wallet trigger denominated in credits`**

```json A wallet trigger denominated in credits
{
  "object_type": "WORKFLOW_TRIGGER",
  "id": "wft_8LmPc5XrvNbTeK4QjYZ9H",
  "type": "EVENT",
  "wallet": {
    "wallet_id": "wall_3TnRk9YbvQdMeF6WpXJ2L",
    "wallet_type_id": "wtyp_5RmXe2QbtKfYuA9DcNH3P",
    "wallet_reference": "prepaid-credits",
    "event": { "variant": "WALLET_BALANCE" },
    "wallet_balance": {
      "open_balance": { "credits": { "quantity": "40", "credit_type_id": "ctyp_2PnBx7VdtRgLmE4WcQJ8K" } },
      "threshold": { "credits": { "quantity": "100", "credit_type_id": "ctyp_2PnBx7VdtRgLmE4WcQJ8K" } }
    }
  }
}
```

A wallet type funded with an amount keeps its ledger in a currency, and its trigger reports `amount` in the same two places instead:

**`The same block for a wallet denominated in a currency`**

```json The same block for a wallet denominated in a currency
"wallet_balance": {
  "open_balance": { "amount": { "quantity": "40.50", "currency": "EUR" } },
  "threshold": { "amount": { "quantity": "100.00", "currency": "EUR" } }
}
```

> **Warning**
>
> Before release 1.186 both fields were a bare credits object, as in `"open_balance": { "quantity": "40", "credit_type_id": "ctyp_..." }`. A consumer reading `open_balance.quantity` has to move to `open_balance.credits.quantity`. The [send-email action](/platform-guides/workflows/workflow-actions) is unaffected: its `wallet_balance` and `wallet_balance_threshold` variables are rendered figures either way, and `credit_unit_name` carries the currency code when the wallet is denominated in an amount.

### Find the triggers for a resource

Use search when you are answering "did this invoice get its email?". [POST /v1/workflow-triggers/search](https://docs.solvimon.com/api-docs/transaction-api/workflow-triggers/post-workflow-triggers-search) takes the platform's standard `filter_fields` structure, where each entry names a field on the trigger:

**`Search triggers for one customer`**

```bash Search triggers for one customer
curl -X POST https://test.api.solvimon.com/v1/workflow-triggers/search \
  -H "X-API-KEY: <apiKey>" \
  -H "Content-Type: application/json" \
  -d '{
    "filter_fields": [
      { "name": "workflow_id", "value": "wf_7KcQm1RtbXeUvL2NpHZ4S" },
      { "name": "customer_id", "value": "cust_AbD3DqausjOYiMNDZY11F" }
    ]
  }'
```

Use `values` instead of `value` to match a list, and combine with the `limit`, `page` and `order_by` query parameters to page through the results.

An empty result means the workflow never matched. Triggers carry no result of their own, so if a trigger exists but no email went out, check the execution result on the workflow's page in Desk; see [Monitoring and audit](/platform-guides/workflows/monitoring-and-audit).

### Via Desk

Triggers appear on the workflow's detail page and on the invoice, payment or subscription itself, so you can start from either end of the question.

## Troubleshooting

Work through this in order when an email did not arrive:

1. Is the workflow `ACTIVE`? A `DRAFT` or `INACTIVE` workflow never produces triggers.
2. Is the customer in scope? Check `customer_ids` on the workflow.
3. Does a trigger exist for the invoice or payment? If not, the event never matched the variant.
4. Is the action `ACTIVE`? A trigger runs only the workflow's active actions.
5. If a trigger exists and the action is active, open the workflow in Desk and read the execution result and error message.
6. If the execution succeeded, the problem is downstream. Check the email provider's own logs.

## API reference

* [Create a workflow trigger](https://docs.solvimon.com/api-docs/transaction-api/workflow-triggers/post-workflow-triggers)
* [List workflow triggers](https://docs.solvimon.com/api-docs/transaction-api/workflow-triggers/get-workflow-triggers)
* [Search workflow triggers](https://docs.solvimon.com/api-docs/transaction-api/workflow-triggers/post-workflow-triggers-search)
* [Get a workflow trigger](https://docs.solvimon.com/api-docs/transaction-api/workflow-triggers/get-workflow-triggers-by-resource-id)