Workflows

Automate your business with event-driven workflows. Define triggers, conditions, and actions that run automatically when events occur.

How It Works

A workflow is a rule that says: when this event happens, if these conditions are met, perform these actions. Workflows run automatically in the background and log every execution for debugging.

1.Trigger — The event that starts the workflow (e.g. order.created).
2.Conditions — Optional filters that must be true for the workflow to proceed (e.g. order total > $100).
3.Actions — One or more actions to execute (e.g. send an email, update inventory).

Create a Workflow

curl -X POST https://vm.whaletools.cloud/v1/stores/{storeId}/workflows \
  -H "x-api-key: wk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Low Stock Alert",
    "description": "Send an email when inventory drops below threshold",
    "trigger": {
      "type": "inventory.low",
      "config": { "threshold": 10 }
    },
    "conditions": [
      { "field": "product.status", "operator": "eq", "value": "active" }
    ],
    "actions": [
      {
        "type": "send_email",
        "config": {
          "to": "inventory@yourstore.com",
          "subject": "Low Stock: {{product.name}}",
          "body": "{{product.name}} (SKU: {{product.sku}}) has dropped to {{inventory.quantity}} units at {{location.name}}."
        }
      }
    ],
    "is_active": true
  }'

// Response (201 Created)
{
  "object": "workflow",
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "Low Stock Alert",
  "trigger": { "type": "inventory.low" },
  "is_active": true,
  "total_runs": 0,
  "created_at": "2026-03-09T12:00:00.000Z"
}

Trigger Types

Trigger	Description
order.created	Fires when a new order is placed.
order.updated	Fires when an order status, payment, or fulfillment changes.
order.cancelled	Fires when an order is cancelled.
inventory.low	Fires when stock drops below the configured threshold.
inventory.adjusted	Fires when stock levels are manually adjusted.
customer.created	Fires when a new customer registers.
customer.updated	Fires when a customer profile is modified.
product.created	Fires when a new product is added to the catalog.
product.updated	Fires when product details change.
checkout.completed	Fires when a checkout is finalized into an order.
schedule.cron	Fires on a cron schedule (e.g. daily at 9am).

Action Types

Action	Description
send_email	Send an email using a template or custom body.
update_inventory	Adjust stock levels for a product at a location.
create_task	Create a task in the store task queue.
webhook	Send a POST request to an external URL with the event payload.
send_sms	Send an SMS notification to a phone number.
tag_customer	Add or remove tags on a customer profile.
create_order_note	Add an internal note to an order.

Conditions

Conditions filter which events actually trigger the workflow. Each condition specifies a field, operator, and value. All conditions must be true for the workflow to run.

"conditions": [
  { "field": "order.total", "operator": "gte", "value": 100 },
  { "field": "order.payment_method", "operator": "eq", "value": "card" },
  { "field": "customer.tags", "operator": "contains", "value": "vip" }
]

// Supported operators:
// eq       — equals
// neq      — not equals
// gt       — greater than
// gte      — greater than or equal
// lt       — less than
// lte      — less than or equal
// contains — array/string contains value
// in       — value is in array

Template Variables

Use double curly braces to reference event data in action configurations. Variables are resolved at execution time from the trigger event payload.

// Available variables depend on the trigger type

// order triggers
{{order.id}}
{{order.order_number}}
{{order.total}}
{{order.status}}
{{customer.name}}
{{customer.email}}

// inventory triggers
{{product.name}}
{{product.sku}}
{{inventory.quantity}}
{{location.name}}

// customer triggers
{{customer.id}}
{{customer.name}}
{{customer.email}}
{{customer.phone}}

Workflow Runs

Every workflow execution is logged. View run history to debug failures, check action results, and monitor performance.

// List workflow runs
curl https://vm.whaletools.cloud/v1/stores/{storeId}/workflows/{workflowId}/runs \
  -H "x-api-key: wk_live_your_key_here"

// Response
{
  "object": "list",
  "data": [
    {
      "id": "run_abc123",
      "status": "completed",
      "trigger_event": "inventory.low",
      "actions_executed": 1,
      "started_at": "2026-03-09T12:00:00.000Z",
      "completed_at": "2026-03-09T12:00:01.234Z"
    }
  ],
  "has_more": false
}