run

Triggers another script to run asynchronously. The triggered script runs independently in the background, and you can pass data to it via a payload object.

{% json payload %}
  {
    "order_id": {{ order.id }},
    "customer_email": "{{ customer.email }}"
  }
{% endjson %}

{% run "process_order", payload %}

Syntax

{% run "script_handle", payload %}
{% run "script_handle", payload, delay: seconds %}
{% run script_variable, payload %}

Parameters

Parameter	Required	Description
script_handle	Yes	Handle or ID of the script to trigger (string in quotes or variable)
payload	No	Object containing data to pass to the triggered script
delay	No	Number of seconds to wait before running the script

Behavior

• The triggered script runs asynchronously (the current script continues immediately)

• Payload variables become directly accessible in the triggered script

• The script must exist and be active

• Recursive runs are prevented (a script cannot trigger itself directly or through a chain)

• If the script is not found, a warning is logged

Examples

Basic script trigger:

{% run "send_notifications" %}

Trigger with payload:

{% json payload %}
  {
    "order_id": {{ order.id }},
    "total": {{ order.total_price }},
    "email": "{{ customer.email }}"
  }
{% endjson %}

{% run "order_processor", payload %}

In the triggered script (order_processor), access the variables directly:

{% comment %} Inside order_processor script {% endcomment %}
{% log "Processing order: " | append: order_id %}
{% log "Total: " | append: total %}
{% log "Customer: " | append: email %}

Trigger with delay:

{% comment %} Run script after 60 seconds {% endcomment %}
{% json payload %}
  {
    "reminder_type": "abandoned_cart",
    "cart_id": {{ cart.id }}
  }
{% endjson %}

{% run "send_reminder", payload, delay: 60 %}

Dynamic delay based on condition:

{% if customer.vip %}
  {% assign wait_time = 30 %}
{% else %}
  {% assign wait_time = 300 %}
{% endif %}

{% run "follow_up_email", payload, delay: wait_time %}

Trigger script using variable for handle:

{% assign script_name = "process_" | append: order.type %}
{% run script_name, payload %}

Chain multiple scripts:

{% comment %} Trigger multiple independent scripts {% endcomment %}
{% json order_data %}
  {"order_id": {{ order.id }}}
{% endjson %}

{% run "update_inventory", order_data %}
{% run "notify_warehouse", order_data %}
{% run "send_confirmation", order_data %}

{% log "All scripts triggered" %}

Conditional script trigger:

{% if order.total_price > 1000 %}
  {% json vip_payload %}
    {
      "order_id": {{ order.id }},
      "priority": "high"
    }
  {% endjson %}
  {% run "vip_order_handler", vip_payload %}
{% else %}
  {% run "standard_order_handler", order_data %}
{% endif %}

Pass complex nested data:

{% json payload %}
  {
    "order": {
      "id": {{ order.id }},
      "name": "{{ order.name }}",
      "items": {{ order.line_items | json }}
    },
    "customer": {
      "id": {{ customer.id }},
      "email": "{{ customer.email }}",
      "tags": {{ customer.tags | split: ", " | json }}
    },
    "metadata": {
      "triggered_at": "{{ 'now' | date: '%Y-%m-%dT%H:%M:%SZ' }}",
      "source": "main_processor"
    }
  }
{% endjson %}

{% run "data_sync", payload %}

Scheduled batch processing:

{% comment %} Process items in batches with delays {% endcomment %}
{% assign batch_size = 10 %}
{% assign delay_between = 5 %}

{% for item in items %}
  {% assign batch_number = forloop.index | divided_by: batch_size %}
  {% assign item_delay = batch_number | times: delay_between %}

  {% json item_payload %}
    {
      "item_id": {{ item.id }},
      "action": "process"
    }
  {% endjson %}

  {% run "process_item", item_payload, delay: item_delay %}
{% endfor %}

Trigger by script ID:

{% comment %} You can also use the script's MongoDB ID {% endcomment %}
{% run "507f1f77bcf86cd799439011", payload %}

Error handling pattern:

{% json error_payload %}
  {
    "error_message": "{{ error_message }}",
    "script_name": "main_processor",
    "timestamp": "{{ 'now' | date: '%Y-%m-%dT%H:%M:%SZ' }}"
  }
{% endjson %}

{% run "error_handler", error_payload %}

Use Cases

Scenario	Description
Background processing	Offload heavy tasks to run asynchronously
Delayed actions	Schedule follow-ups, reminders, or retries
Event fan-out	Trigger multiple scripts from a single event
Modular workflows	Break complex processes into smaller scripts
Error handling	Trigger dedicated error handling scripts
Batch processing	Process large datasets with controlled timing

Notes

• The current script does not wait for the triggered script to complete

• Recursive runs are blocked - a script cannot directly or indirectly trigger itself

• If the script handle is not found, a warning is logged but execution continues

• The script must be active to be triggered

• Use the delay parameter for rate limiting or scheduling

• Payload data is passed as-is - ensure proper JSON formatting

• Both script handle (name) and script ID can be used to reference the script