Automation definition

An automation definition is a trigger and an ordered list of steps. The Automation Builder writes one for you when you describe what you want in chat. Write one yourself when you build automations over the API or an MCP client.

Required fields

Field	Type	Notes
`name`	string	1 to 200 characters
`trigger_type`	string	What starts the automation. See Choosing a trigger
`steps`	array	1 to 50 steps. See Step types

Optional fields

Field	Type	Notes
`description`	string	What the automation does, for people reading it later
`summary`	string	One line shown on the automation card
`instructions`	string	Extra guidance for agent-callable automations. Up to 2000 characters
`destructive`	boolean	Marks the automation as making changes that cannot be undone. Defaults to `false`
`schedule_config`	object	Required when `trigger_type` is `SCHEDULE`, and rejected otherwise
`input_schema`	object	Required when `trigger_type` is `function`

Choosing a trigger

trigger_type takes one of three kinds of value. A project event fires the automation when something happens in your store, such as ORDER_CREATED or CUSTOMER_UPDATED. Browse them in Events. Connection webhooks use the connection’s own event id, such as shopify/orders/paid. SCHEDULE runs the automation on a clock. Pair it with schedule_config, whose fields are in Scheduled:

{
  "trigger_type": "SCHEDULE",
  "schedule_config": { "schedule_type": "cron", "cron_expression": "0 9 * * MON" }
}

function makes the automation callable by an agent rather than fired by an event. Declare what the caller passes in input_schema:

{
  "trigger_type": "function",
  "input_schema": {
    "type": "object",
    "properties": { "order_id": { "type": "string" } },
    "required": ["order_id"]
  }
}

Referencing data

Steps read values with {{...}} templates rather than literals. Data access covers the rules; the namespaces are:

Namespace	Reads
`{{<field>}}`	A field of the trigger’s own payload, by its bare name
`{{trigger_data.payload.*}}`	The same payload through its envelope
`{{steps.<id>.*}}`	An earlier step’s output
`{{iteration.item.*}}`	The current item inside a `map` step
`{{now}}`, `{{workspace.}}`, `{{platform.}}`	Run context the engine supplies

There is no {{payload.*}} namespace. A function trigger’s inputs are trigger payload fields like any other, so an input_schema property named order_id is {{order_id}}.

A complete definition

This automation runs every Monday morning, asks for last week’s revenue, and posts it to Slack.

{
  "name": "Weekly revenue summary",
  "description": "Posts last week's revenue to Slack every Monday.",
  "trigger_type": "SCHEDULE",
  "schedule_config": {
    "schedule_type": "cron",
    "cron_expression": "0 9 * * MON"
  },
  "steps": [
    {
      "id": "revenue",
      "type": "insights",
      "description": "Read last week's revenue",
      "question": "What was total revenue and order count for the last 7 days?",
      "output_schema": {
        "type": "object",
        "properties": {
          "revenue": { "type": "number" },
          "orders": { "type": "integer" }
        },
        "required": ["revenue", "orders"]
      },
      "next": "post"
    },
    {
      "id": "post",
      "type": "action",
      "description": "Post the summary to Slack",
      "action": "slack/send_message",
      "parameters": {
        "channel": "#general",
        "text": "Last week: {{steps.revenue.revenue}} across {{steps.revenue.orders}} orders."
      }
    }
  ]
}

Each step type takes its own fields on top of id and type. Step types lists them, and marks which are required.

Checking a definition

Validate a definition before you create it. The checker runs the same rules the platform runs on create, over a whole definition or a single step, so what it accepts is what the platform accepts. See the MCP server for the tools that expose it.

Get started

Platform

Agents

Automations

Storefront

Dev Tools

Automation definition

Required fields

Optional fields

Choosing a trigger

Referencing data

A complete definition

Checking a definition

​Required fields

​Optional fields

​Choosing a trigger

​Referencing data

​A complete definition

​Checking a definition

Required fields

Optional fields

Choosing a trigger

Referencing data

A complete definition

Checking a definition