> ## Documentation Index
> Fetch the complete documentation index at: https://docs.firmhouse.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Script Execution workflow

> Create a Script Execution workflow that runs custom JavaScript from outgoing webhook events and returns Firmhouse Journey actions for automation.

Script Execution lets you run custom JavaScript from an outgoing webhook event. Your script receives the subscription and webhook context as `input` and must return one or more Firmhouse actions for the Journey to execute.

<Info>
  Script Execution is currently a private beta feature. During the beta, Firmhouse staff needs to enable it for your project.
</Info>

> **Note:** Contact Firmhouse Support to enable this feature for your project. This feature is only available for Advanced or higher tier merchants.

## What it is

Script Execution is useful when you need custom Journey logic that is not covered by the standard workflow presets. An outgoing webhook starts the workflow when its selected event happens. Instead of directly changing a subscription from the script, your script decides which supported action Firmhouse should execute next.

The script:

* must contain valid JavaScript
* receives the subscription and webhook trigger context as `input`
* must `return` an array of action objects
* cannot perform direct side effects in Firmhouse by itself

## Add a Script Execution workflow

1. Ask the Firmhouse support team to enable the **Script Execution** beta for your project.
2. Open your project in the Firmhouse portal.
3. In the sidebar, go to **Workflows**.
4. Click **Create new workflow**.
5. Choose **Script Execution**.
6. Enter a name for the workflow and optionally add a description.
7. Paste your JavaScript into the script editor.
8. Optionally, add **Input Parameters** (see below).
9. Click **Save workflow**.
10. In the sidebar, go to **Apps**.
11. Find the **Webhooks** app and click **Configure**.
12. Click **New outgoing webhook**.
13. Set **Content type** to **Script Execution**.
14. Select the Script Execution workflow you created.
15. Select the **Event** that should run the script.
16. Optionally, add a JSON **Template**. The rendered template is passed to the script as `input.trigger.payload`.
17. Make sure the webhook is enabled and click **Save**.

## Input Parameters

Input Parameters let you define key/value pairs that become available in your script. This lets you write a single reusable script and configure it differently per workflow — without editing JavaScript.

Your script receives the parameters in two forms:

* `input.params` — the raw array of parameter objects exactly as configured, e.g. `[{"key": "order_1", "type": "product", "value": "gid://..."}, ...]`. Use this when you need access to the full metadata (type, individual entries).
* `input.params_normalized` — a convenience hash that groups values by key, e.g. `{"order_1": "gid://...", "order_2": ["gid://...", "gid://..."]}`. Duplicate keys are automatically collected into arrays. Use this for simple key-based lookups.

To add parameters, expand the **Input Parameters** section on the workflow form, click **+ Add parameter**, enter a key and value, and save.

### Parameter types

Each parameter has a **Type** selector:

* **Text** (default) — Enter any plain text value. The value is always passed to your script as a string. If you need array-like behaviour, use a comma-separated or pipe-separated value and split it in your script (e.g. `"a,b,c".split(",")`).
* **Product** — Select a product from your catalog using a search autocomplete field. This makes it easy to deterministically reference a specific product in your input parameters without needing to look up its ID. The selected product's Global ID is stored and passed to your script as a string (e.g. `"gid://firmhouse/Product/123"`).

You can use the same key multiple times. For example, two rows with key `order_2` and type Product will appear as two separate entries in `input.params`. In `input.params_normalized`, they are grouped into an array: `input.params_normalized.order_2` → `["gid://firmhouse/Product/101", "gid://firmhouse/Product/102"]`.

## The script protocol

Your script must return an array. Each item in the array must be an object with:

* `function`
* `arguments`

For example:

```javascript theme={null}
return [
  {
    function: "no_action",
    arguments: {
      reason: `No follow-up action is needed for subscription signed up at ${input.signed_up_at}`
    }
  }
]
```

### Rules

* The script must use valid JavaScript syntax.
* The script must `return [...]`, not `{ actions: [...] }`.
* The returned value must be an array.
* Each action must be an object.
* `function` must be one of the supported function names listed below.
* `arguments` must be an object.
* Required arguments must be present.
* Extra arguments are rejected.
* Argument types must match the expected types.

## Copy-paste examples

### No-op / smoke test

Use this script to verify that the workflow executes successfully without changing the subscription.

```javascript theme={null}
return [
  {
    function: "no_action",
    arguments: {
      reason: `signed up ${input.signed_up_at}`
    }
  }
]
```

### Product swap example

Use this script as a starting point for a workflow that supports multiple source-to-target product mappings and returns one swap action for each matching current product.

```javascript theme={null}
const productMappings = [
  {
    source_product_id: "gid://firmhouse/Product/101",
    target_product_id: "gid://firmhouse/Product/201"
  },
  {
    source_product_id: "gid://firmhouse/Product/102",
    target_product_id: "gid://firmhouse/Product/202"
  }
]

const actions = productMappings.flatMap((mapping) => {
  const matchingProduct = input.current_products.find((product) => {
    return product.id === mapping.source_product_id
  })

  if (!matchingProduct) return []

  return [
    {
      function: "swap_product_by_id",
      arguments: {
        current_product_id: matchingProduct.id,
        new_product_id: mapping.target_product_id,
        reason: `Swap ${matchingProduct.title} based on configured product mapping`
      }
    }
  ]
})

if (actions.length === 0) {
  return [
    {
      function: "no_action",
      arguments: { reason: "No configured source products were found on this subscription" }
    }
  ]
}

return actions
```

### Promotion by confirmed orders count

Use this script when you want to apply different promotions after specific order milestones. In this example, one promotion is applied after 3 confirmed orders and another after 6 confirmed orders.

```javascript theme={null}
const promotionByConfirmedOrders = {
  3: "gid://firmhouse/Promotion/301",
  6: "gid://firmhouse/Promotion/302"
}

const promotionId = promotionByConfirmedOrders[input.confirmed_orders_count]

if (!promotionId) {
  return [
    {
      function: "no_action",
      arguments: {
        reason: `No promotion configured for ${input.confirmed_orders_count} confirmed orders`
      }
    }
  ]
}

return [
  {
    function: "apply_promotion",
    arguments: {
      promotion_id: promotionId,
      reason: `Apply the configured promotion after ${input.confirmed_orders_count} confirmed orders`
    }
  }
]
```

### Add a free one-off product on a configured order

Use this script when you want to add a free product to a specific upcoming order. The product is added as a one-off add-on, so it is included in that order only.

For example, to ship a loyalty reward with order 3, configure the workflow to add it on order 3. Script Execution runs after an order is confirmed, so the action is returned after order 2 is confirmed and prepares the subscription for order 3.

Configure the Input Parameters like this:

| Key              | Type    | Value                                                           |
| ---------------- | ------- | --------------------------------------------------------------- |
| `product_to_add` | Product | The product to add for free                                     |
| `add_on_order`   | Text    | The order number that should include the free product, e.g. `3` |
| `quantity`       | Text    | Optional quantity, e.g. `1`                                     |

```javascript theme={null}
const params = input.params_normalized

const productId = params.product_to_add
const addOnOrder = Number.parseInt(params.add_on_order || "", 10)
const quantity = Number.parseInt(params.quantity || "1", 10)
const confirmedOrdersCount = input.confirmed_orders_count
const orderToPrepare = confirmedOrdersCount + 1

if (!productId) {
  return [
    {
      function: "no_action",
      arguments: {
        reason: "No product_to_add configured."
      }
    }
  ]
}

if (!Number.isFinite(addOnOrder) || addOnOrder < 2) {
  return [
    {
      function: "no_action",
      arguments: {
        reason: `Invalid add_on_order value: ${params.add_on_order}`
      }
    }
  ]
}

if (orderToPrepare === addOnOrder) {
  return [
    {
      function: "add_gift_to_subscription",
      arguments: {
        product_id: productId,
        quantity: String(Number.isFinite(quantity) && quantity > 0 ? quantity : 1),
        reason: `Add configured free one-off product so it ships with order ${addOnOrder}.`
      }
    }
  ]
}

return [
  {
    function: "no_action",
    arguments: {
      reason: `No configured free product due for order ${orderToPrepare}.`
    }
  }
]
```

### Product sequence with revolving cycle

Some subscription businesses ship different products depending on where the subscriber is in their journey. For example, a health supplements brand might send a starter kit on the first order, then alternate between two different refill packs from order 2 onward. After the first checkout order and possible follow-up orders, you can configure a revolving cycle that spans multiple orders.

This script uses **Input Parameters** to configure which products belong to each order in the sequence. You do not need to edit the JavaScript — just set the parameters in the workflow form.

#### Real-world example

Imagine a supplements brand that works like this:

* The customer checks out with a **Starter Kit** (order 1).
* On order 2, the subscription switches to two refill products: **Refill Pack A** and **Refill Pack B**.
* On order 3, the subscription has only **Refill Pack A**.
* From order 4 onward, orders 2 and 3 keep repeating: the customer alternates between receiving both refill packs and just one.

To set this up, you configure the Input Parameters like this:

| Key                    | Type    | Value         |
| ---------------------- | ------- | ------------- |
| `order_1`              | Product | Starter Kit   |
| `order_2`              | Product | Refill Pack A |
| `order_2`              | Product | Refill Pack B |
| `order_3`              | Product | Refill Pack A |
| `restart_from_order_2` | Text    | `true`        |

The resulting order sequence:

* Order 1 → Starter Kit (checkout order — already on subscription at signup)
* Order 2 → Refill Pack A + Refill Pack B (removes Starter Kit, adds both refills)
* Order 3 → Refill Pack A (removes Refill Pack B, keeps Refill Pack A)
* Order 4 → Refill Pack A + Refill Pack B (cycles back to order 2)
* Order 5 → Refill Pack A (cycles back to order 3)
* ...and so on

#### How the Input Parameters work

Each key follows the `order_X` format, where `X` is the order number. Set the type to **Product** and search for the product you want.

To add **multiple products to the same order**, add multiple rows with the same key (e.g. two rows both named `order_2`, each with a different product). The script collects all products for that order automatically.

`order_1` represents the **checkout order** — the products the customer receives at signup. These are already on the subscription, so the script does not add them. It uses `order_1` to know which products to remove when moving to `order_2`.

Add a key named `restart_from_order_X` (e.g. `restart_from_order_2`) with any value (e.g. `true`) to set where the revolving cycle begins. Once all configured orders have been fulfilled, the sequence loops back to this order number and repeats indefinitely.

#### The script

Paste this script into the Script Execution workflow. It reads the Input Parameters and handles add/remove automatically.

```javascript theme={null}
const params = input.params_normalized
const orderCount = input.confirmed_orders_count
const currentProducts = input.current_products || []

// Collect order_X keys and parse step numbers
const stepNumbers = Object.keys(params)
  .filter(k => k.startsWith("order_"))
  .map(k => parseInt(k.split("_")[1]))
  .filter(n => !isNaN(n))
  .sort((a, b) => a - b)
// Deduplicate step numbers (same key can appear in multiple rows)
const uniqueSteps = [...new Set(stepNumbers)]

if (uniqueSteps.length === 0) {
  return [{ function: "no_action", arguments: { reason: "No order_X steps configured in input params" } }]
}

const maxStep = uniqueSteps[uniqueSteps.length - 1]

// Find restart_from_order_X key to determine revolving cycle start
let alternateFrom = uniqueSteps[0]
for (const key of Object.keys(params)) {
  const match = key.match(/^restart_from_order_(\d+)$/)
  if (match) {
    alternateFrom = parseInt(match[1])
    break
  }
}

// The script runs after each order is confirmed.
// We prepare the subscription for the NEXT order.
// order_1 is the checkout order — its products are already on the subscription at signup.
// After order 1 is confirmed (orderCount=1), we swap to order_2 products, etc.
if (orderCount < 1) {
  return [{ function: "no_action", arguments: { reason: "No confirmed orders yet" } }]
}

const nextOrder = orderCount + 1

// Determine which step to prepare for
let effectiveStep
if (nextOrder <= maxStep) {
  effectiveStep = nextOrder
} else {
  // Revolving cycle: loop from alternateFrom to maxStep
  const cycleLength = maxStep - alternateFrom + 1
  const offset = (nextOrder - alternateFrom) % cycleLength
  effectiveStep = alternateFrom + offset
}

// Get the target product IDs for this step
// Supports both single values and arrays (from duplicate keys)
const stepKey = "order_" + effectiveStep
const rawTarget = params[stepKey]
const targetProductIds = Array.isArray(rawTarget) ? rawTarget : (rawTarget ? [rawTarget] : [])

if (targetProductIds.length === 0) {
  return [{ function: "no_action", arguments: { reason: "No products defined for step " + effectiveStep } }]
}

const currentProductIds = currentProducts.map(p => p.id)
const actions = []

// Remove products that should no longer be on the subscription
for (const currentId of currentProductIds) {
  if (!targetProductIds.includes(currentId)) {
    actions.push({
      function: "remove_product_from_subscription",
      arguments: {
        product_id: currentId,
        reason: "Removing product not in order_" + effectiveStep + " of sequence"
      }
    })
  }
}

// Add products that should be on the subscription but are not yet
for (const targetId of targetProductIds) {
  if (!currentProductIds.includes(targetId)) {
    actions.push({
      function: "add_product_to_subscription",
      arguments: {
        product_id: targetId,
        reason: "Adding product for order_" + effectiveStep + " of sequence"
      }
    })
  }
}

if (actions.length === 0) {
  return [{ function: "no_action", arguments: { reason: "Products already match order_" + effectiveStep } }]
}

return actions
```

## Supported functions

### `no_action`

Use this when the Journey should continue without making any subscription change right now.

Required arguments:

* `reason` (`string`)

Example:

```javascript theme={null}
return [
  {
    function: "no_action",
    arguments: {
      reason: "The subscription already matches the expected configuration."
    }
  }
]
```

### `swap_product_by_id`

Use this to replace one product on the subscription with another product.

Required arguments:

* `current_product_id` (`string`)
* `new_product_id` (`string`)
* `reason` (`string`)

Both product IDs must be Firmhouse product Global IDs.

Use the `firmhouse` namespace in these Global IDs, for example `gid://firmhouse/Product/123`. Do not use `gid://gomonthly/...`, because those IDs will not work in Script Execution workflows.

Example:

```javascript theme={null}
const currentProduct = input.current_products[0]

if (!currentProduct) {
  return [
    {
      function: "no_action",
      arguments: { reason: "No current product found." }
    }
  ]
}

return [
  {
    function: "swap_product_by_id",
    arguments: {
      current_product_id: currentProduct.id,
      new_product_id: "gid://firmhouse/Product/123",
      reason: "Move the subscriber to the recurring refill product."
    }
  }
]
```

### `update_next_billing_date`

Use this to move the subscription's next billing date.

Required arguments:

* `next_billing_date` (`string`, ISO date format `YYYY-MM-DD`)
* `reason` (`string`)

Example:

```javascript theme={null}
return [
  {
    function: "update_next_billing_date",
    arguments: {
      next_billing_date: "2026-05-15",
      reason: "Align billing with the customer’s requested charge date."
    }
  }
]
```

### `update_plan_commitment_dates`

Use this to update the subscription plan's commitment dates. This is useful when a workflow needs to set, extend, or clear the plan's minimum commitment, maximum commitment, or grace cancellation dates.

Required arguments:

* `reason` (`string`)

Optional arguments:

* `minimum_commitment_ends_at` (`string`, ISO date or timestamp)
* `maximum_commitment_ends_at` (`string`, ISO date or timestamp)
* `grace_cancellation_ends_at` (`string`, ISO date or timestamp)

Pass an empty string for a date argument to clear that date.

Example:

```javascript theme={null}
return [
  {
    function: "update_plan_commitment_dates",
    arguments: {
      minimum_commitment_ends_at: "2026-12-31",
      maximum_commitment_ends_at: "2026-12-31",
      reason: "Align commitment dates with the renewed 6-month cycle."
    }
  }
]
```

### `apply_promotion`

Use this to apply a promotion to the subscription.

Required arguments:

* `promotion_id` (`string`)
* `reason` (`string`)

Example:

```javascript theme={null}
return [
  {
    function: "apply_promotion",
    arguments: {
      promotion_id: "123",
      reason: "Apply the onboarding discount after activation."
    }
  }
]
```

### `add_product_to_subscription`

Use this to add a product to the subscription.

Required arguments:

* `product_id` (`string`) — Firmhouse product Global ID
* `reason` (`string`)

Optional arguments:

* `quantity` (`string`) — defaults to `"1"` if not provided

Example:

```javascript theme={null}
return [
  {
    function: "add_product_to_subscription",
    arguments: {
      product_id: "gid://firmhouse/Product/123",
      reason: "Add the refill product for this cycle."
    }
  }
]
```

### `add_gift_to_subscription`

Use this to add a free one-off product to the subscription. The product is added for the next order only and is removed from the subscription after that order is created.

Required arguments:

* `product_id` (`string`) — Firmhouse product Global ID
* `reason` (`string`)

Optional arguments:

* `quantity` (`string`) — defaults to `"1"` if not provided

Example:

```javascript theme={null}
return [
  {
    function: "add_gift_to_subscription",
    arguments: {
      product_id: "gid://firmhouse/Product/123",
      quantity: "1",
      reason: "Add the loyalty present for the next order."
    }
  }
]
```

### `add_one_off_product_to_subscription`

Use this to add a one-off product to the subscription with an optional custom price. The product is added for the next order only and is removed from the subscription after that order is created.

Required arguments:

* `product_id` (`string`) — Firmhouse product Global ID
* `reason` (`string`)

Optional arguments:

* `quantity` (`string`) — defaults to `"1"` if not provided
* `custom_price_cents` (`string` or `number`) — custom price in cents. Use `0` for a free product.
* `skip_billing_product_replacement` (`boolean`) — set to `true` when the subscription's plan uses a Shopify billing product, but this one-off product should use its own Shopify variant instead of the billing product variant.

Example:

```javascript theme={null}
return [
  {
    function: "add_one_off_product_to_subscription",
    arguments: {
      product_id: "gid://firmhouse/Product/123",
      quantity: "1",
      custom_price_cents: 500,
      skip_billing_product_replacement: true,
      reason: "Add a discounted sample for the next order."
    }
  }
]
```

### `remove_product_from_subscription`

Use this to remove a product from the subscription.

Required arguments:

* `product_id` (`string`) — Firmhouse product Global ID
* `reason` (`string`)

Example:

```javascript theme={null}
return [
  {
    function: "remove_product_from_subscription",
    arguments: {
      product_id: "gid://firmhouse/Product/123",
      reason: "Remove the starter product after the bootstrap phase."
    }
  }
]
```

### `update_ordered_product_metadata`

Use this to replace the metadata object on an active ordered product. This is useful when a workflow needs to store data on the subscribed item itself, such as fulfillment metadata, external references, or configuration copied from an order event.

Required arguments:

* `ordered_product_id` (`string` or `integer`) — Firmhouse ordered product ID or Firmhouse ordered product Global ID
* `metadata` (`object`) — metadata to save on the ordered product
* `reason` (`string`)

The metadata object replaces the ordered product's existing metadata. Include any existing keys you want to keep.

Example: increment how many times each ordered product has been shipped. This assumes your webhook template includes each line's current ordered product metadata as `ordered_product_metadata`.

```javascript theme={null}
const orderLines = input.trigger.payload.order_lines || []

return orderLines
  .filter((line) => line.ordered_product_id)
  .map((line) => {
    const metadata = line.ordered_product_metadata || {}
    const timesShipped = Number(metadata.times_shipped || 0)

    return {
      function: "update_ordered_product_metadata",
      arguments: {
        ordered_product_id: line.ordered_product_id,
        metadata: {
          ...metadata,
          times_shipped: timesShipped + 1
        },
        reason: "Increment the shipped count on the ordered product."
      }
    }
  })
```

### `confirm_order`

Use this to confirm an order that is awaiting confirmation. This is useful when a Script Execution workflow checks the order and decides it can continue.

Required arguments:

* `order_id` (`string` or `integer`) — Firmhouse order ID or Firmhouse order Global ID for the awaiting confirmation order
* `reason` (`string`)

Example:

```javascript theme={null}
return [
  {
    function: "confirm_order",
    arguments: {
      order_id: input.trigger.payload.order_id,
      reason: "The order passed the configured checks."
    }
  }
]
```

### `skip_order`

Use this to skip an order that is awaiting confirmation.

Required arguments:

* `order_id` (`string` or `integer`) — Firmhouse order ID or Firmhouse order Global ID for the awaiting confirmation order
* `reason` (`string`)

Example:

```javascript theme={null}
return [
  {
    function: "skip_order",
    arguments: {
      order_id: input.trigger.payload.order_id,
      reason: "The order should not be created for this cycle."
    }
  }
]
```

### `schedule_order`

Use this to move a confirmed order back to the scheduled state with a future shipment date. For example, an **Order confirmed** outgoing webhook can trigger a Script Execution workflow that delays fulfillment until a date chosen by your business rules.

Required arguments:

* `order_id` (`string` or `integer`) — Firmhouse order ID or Firmhouse order Global ID for a confirmed order on the current subscription
* `shipment_date` (`string`) — future shipment date in `YYYY-MM-DD` format
* `reason` (`string`)

The action only changes confirmed orders. Running it again after the order is already scheduled for the same date has no additional effect. If the order has a Shopify fulfillment order, Firmhouse also requests that Shopify use the new fulfillment date.

For an **Order confirmed** webhook, add an order ID to the webhook template:

```json theme={null}
{
  "order_id": {{ order.id }}
}
```

The following example reads the shipment date from a Text input parameter named `shipment_date`:

```javascript theme={null}
return [
  {
    function: "schedule_order",
    arguments: {
      order_id: input.trigger.payload.order_id,
      shipment_date: input.params_normalized.shipment_date,
      reason: "Delay fulfillment until the configured shipment date."
    }
  }
]
```

### `add_order_line`

Use this to add a product line to an order that is awaiting confirmation.

Required arguments:

* `order_id` (`string` or `integer`) — Firmhouse order ID or Firmhouse order Global ID for the awaiting confirmation order
* `product_id` (`string` or `integer`) — Firmhouse product ID or Firmhouse product Global ID
* `reason` (`string`)

Optional arguments:

* `quantity` (`string` or `integer`) — defaults to `1` if not provided. Must be `1` or greater.
* `price_cents` (`string` or `integer`) — optional unit price in cents. Defaults to the product price when not provided. Use `0` for a free line.

Example:

```javascript theme={null}
return [
  {
    function: "add_order_line",
    arguments: {
      order_id: input.trigger.payload.order_id,
      product_id: "gid://firmhouse/Product/123",
      quantity: 1,
      price_cents: 0,
      reason: "Add a free sample to this order."
    }
  },
  {
    function: "confirm_order",
    arguments: {
      order_id: input.trigger.payload.order_id,
      reason: "The order is ready after adding the sample."
    }
  }
]
```

### `remove_order_line`

Use this to remove a product line from an order that is awaiting confirmation. The line is selected by the ordered product ID behind that order line.

Required arguments:

* `order_id` (`string` or `integer`) — Firmhouse order ID or Firmhouse order Global ID for the awaiting confirmation order
* `ordered_product_id` (`string` or `integer`) — Firmhouse ordered product ID or Firmhouse ordered product Global ID for the order line to remove
* `reason` (`string`)

Example:

```javascript theme={null}
return [
  {
    function: "remove_order_line",
    arguments: {
      order_id: input.trigger.payload.order_id,
      ordered_product_id: "gid://firmhouse/OrderedProduct/456",
      reason: "Remove the product from this order because the customer is not eligible."
    }
  },
  {
    function: "confirm_order",
    arguments: {
      order_id: input.trigger.payload.order_id,
      reason: "The order is ready after removing the ineligible product."
    }
  }
]
```

### `replace_order_line`

Use this to replace a product line on an order that is awaiting confirmation. This adds the replacement line before removing the original line, so the order is not left temporarily empty.

Required arguments:

* `order_id` (`string` or `integer`) — Firmhouse order ID or Firmhouse order Global ID for the awaiting confirmation order
* `ordered_product_id` (`string` or `integer`) — Firmhouse ordered product ID or Firmhouse ordered product Global ID for the order line to replace
* `replacement_product_id` (`string` or `integer`) — Firmhouse product ID or Firmhouse product Global ID for the replacement product
* `reason` (`string`)

Optional arguments:

* `quantity` (`string` or `integer`) — defaults to `1` if not provided. Must be `1` or greater.
* `price_cents` (`string` or `integer`) — optional unit price in cents. Defaults to the replacement product price when not provided. Use `0` for a free line.

Example:

```javascript theme={null}
return [
  {
    function: "replace_order_line",
    arguments: {
      order_id: input.trigger.payload.order_id,
      ordered_product_id: "gid://firmhouse/OrderedProduct/456",
      replacement_product_id: "gid://firmhouse/Product/789",
      quantity: 1,
      reason: "Replace the product with the customer's configured alternative."
    }
  },
  {
    function: "confirm_order",
    arguments: {
      order_id: input.trigger.payload.order_id,
      reason: "The order is ready after replacing the product."
    }
  }
]
```

### `stop_journey`

Use this when the Journey has reached its end and should not continue for this subscription.

Required arguments:

* `stop_journey` (`boolean`)
* `reason` (`string`)

Example:

```javascript theme={null}
return [
  {
    function: "stop_journey",
    arguments: {
      stop_journey: true,
      reason: "The workflow has completed all follow-up actions."
    }
  }
]
```

## What `input` contains

Firmhouse passes the current subscription and outgoing webhook context into your script as `input`. Most subscription fields follow a fixed structure. The webhook trigger context tells your script which event started the run and includes the rendered webhook payload.

The current `input` payload contains:

* `signed_up_at`
* `confirmed_orders_count`
* `confirmed_or_fulfilled_orders`
* `current_products`
* `current_promotions`
* `active_plan`
* `trigger` — outgoing webhook context for the event that started the script. `input.trigger.payload` contains the rendered webhook template, so its fields depend on what you include in that template.
* `params` — the raw array of Input Parameter objects you configured on the workflow (empty array `[]` when none are set). Each entry has `key`, `type`, and `value`.
* `params_normalized` — a convenience hash that groups `params` by key. Duplicate keys become arrays. Empty object `{}` when no parameters are set.

Example:

```json theme={null}
{
  "signed_up_at": "2026-04-01T10:15:00Z",
  "confirmed_orders_count": 1,
  "confirmed_or_fulfilled_orders": [
    {
      "id": "gid://firmhouse/Order/1",
      "order_lines": [
        {
          "id": "gid://firmhouse/OrderLine/1",
          "product_id": 123,
          "product_sku": "STARTER-001",
          "quantity": 1
        }
      ]
    }
  ],
  "current_products": [
    {
      "id": "gid://firmhouse/Product/123",
      "product_id": 123,
      "title": "Starter Product",
      "sku": "STARTER-001",
      "quantity": 1,
      "instalment_original_product_id": 123,
      "instalment_current_number": 1
    }
  ],
  "current_promotions": [
    {
      "created_at": "2026-04-01T10:15:00Z",
      "id": "gid://firmhouse/AppliedPromotion/1",
      "promotion_id": "gid://firmhouse/Promotion/1",
      "title": "Welcome Discount",
      "active": "true"
    }
  ],
  "active_plan": {
    "subscribed_plan": {
      "id": "gid://firmhouse/SubscribedPlan/1",
      "next_billing_date": "2026-04-15",
      "billing_cycle_interval_period": 1,
      "billing_cycle_interval_unit": "months",
      "delivery_cycle_interval_period": 1,
      "delivery_cycle_interval_unit": "months",
      "cancellation_strategy": "immediate"
    },
    "plan": {
      "id": "gid://firmhouse/Plan/1",
      "name": "Starter Plan",
      "slug": "starter-plan",
      "instalments": 3,
      "billing_cycle_interval_period": 1,
      "billing_cycle_interval_unit": "months",
      "delivery_cycle_interval_period": 1,
      "delivery_cycle_interval_unit": "months"
    }
  },
  "trigger": {
    "source": "outgoing_webhook",
    "event": "order_pre_confirmation",
    "outgoing_webhook_id": 42,
    "referenceable_gid": "gid://firmhouse/Order/123",
    "payload": {}
  }
}
```

### Field details

* `signed_up_at`
  The subscription sign-up timestamp.
* `confirmed_orders_count`
  The number of confirmed or fulfilled orders on the subscription.
* `confirmed_or_fulfilled_orders`
  The confirmed or fulfilled orders, including their order lines.
* `current_products`
  The currently active products on the subscription, including instalment-related fields:
  `product_id`, `instalment_original_product_id`, and `instalment_current_number`.
* `current_promotions`
  The promotions currently applied to the subscription.
* `active_plan`
  Selected plan details for the subscription, including both `subscribed_plan` attributes and full `plan` attributes.
* `trigger`
  Outgoing webhook context for the event that started the script. This includes `source`, `event`, `outgoing_webhook_id`, and `payload`. If the event is related to a specific record, it can also include `referenceable_gid`. The payload shape depends on the webhook template. The order pre-confirmation examples on this page assume your template includes an `order_id` field, which is then available as `input.trigger.payload.order_id`.

You can inspect the `input` object in your script and use the fields you need in your logic.

`input.params` contains the raw array of parameter objects you defined in the **Input Parameters** section of the workflow form. `input.params_normalized` provides the same data grouped by key for convenient lookups. See [Input Parameters](#input-parameters) for details on how to configure them.

## Troubleshooting

If the script does not save or does not run correctly, check the following:

* the script contains valid JavaScript
* the script returns an array
* every action includes `function` and `arguments`
* all required arguments are present
* there are no extra unsupported arguments
* the argument types match the required types

If the workflow still fails, contact Firmhouse support and include:

* your project ID
* the name of the workflow
* the script you saved
* the action you expected the script to return

## Related articles

* [Post-checkout Product Swap](/configure/workflows/post-checkout-product-swap)