Authoring Playbooks

Playbooks are multi-step automation pipelines that chain specialized Workers into deterministic operational workflows. While individual workers perform isolated tasks (such as generating a report or updating a product), a Playbook orchestrates the sequence: an Analyst digests data, a Planner evaluates options, and an Executor applies the changes.

Merchants and developers author Playbooks in Work Hub to automate recurring commerce processes like inventory replenishment, catalog localization, order exception handling, and customer onboarding.

Playbook Architecture and Data Flow

Playbooks execute sequentially. Output produced by one step is stored in the execution context and made available to subsequent steps through variable references:

Playbook Definition Schema

Playbooks are defined using a structured JSON specification containing metadata, trigger configuration, and an ordered array of steps:

{
  "slug": "automated-stock-replenishment",
  "name": "Automated Stock Replenishment",
  "description": "Identifies low-stock variants, plans reorders with suppliers, and creates draft transfers.",
  "status": "active",
  "triggers": [{ "type": "event", "event_name": "inventory_threshold_breached" }, { "type": "manual" }],
  "steps": [
    {
      "id": "analyze_stock",
      "name": "Analyze Stock Levels",
      "worker_type": "analyst",
      "instructions": "Inspect stock levels across all active fulfillment locations. Identify items with less than 7 days of supply based on 30-day velocity. Output a JSON array of affected variant IDs and quantities.",
      "allowed_tools": ["list_storages", "search_products", "get_product_inventory"],
      "output_variable": "low_stock_items"
    },
    {
      "id": "plan_replenishment",
      "name": "Generate Replenishment Plan",
      "worker_type": "planner",
      "instructions": "Evaluate the low-stock items from {{steps.analyze_stock.low_stock_items}}. Check minimum order quantities and supplier lead times using store guidelines. Propose optimal transfer quantities between warehouses.",
      "allowed_tools": ["get_product", "get_manufacturer_details"],
      "output_variable": "replenishment_plan"
    },
    {
      "id": "review_gate",
      "name": "Merchant Confirmation",
      "require_approval": true,
      "instructions": "Review proposed transfer quantities before writing records."
    },
    {
      "id": "execute_transfers",
      "name": "Create Transfer Records",
      "worker_type": "executor",
      "instructions": "Take the approved replenishment plan from {{steps.plan_replenishment.replenishment_plan}} and create draft warehouse transfers in the system.",
      "allowed_tools": ["create_inventory_transfer", "add_order_note"],
      "output_variable": "transfer_results"
    }
  ]
}

Top-level configuration fields

Step configuration fields

Step Connectivity and Passing Context

Steps pass data downstream through the execution context. You reference previous step outputs in prompt instructions using template placeholders:

{{steps.<step_id>.<output_variable>}}

Example: Passing Analyst findings to Planner

1. Step 1 (analyze_products) outputs a JSON object under flagged_products:

   {
     "flagged_count": 2,
     "products": [
       { "id": 402, "sku": "SHIRT-BLU-S", "issue": "Missing meta description" },
       { "id": 403, "sku": "SHIRT-RED-M", "issue": "Missing Finnish translation" }
     ]
   }

2. Step 2 (generate_fixes) receives that output in its prompt:

   Review the following flagged products from the analysis step:
   {{steps.analyze_products.flagged_products}}
    
   Generate optimized SEO titles and meta descriptions for each item adhering to store brand guidelines.

Lifecycle States

Playbooks follow a managed lifecycle:

• draft: The playbook is under development. It can only be triggered manually by staff with developer permissions. It does not react to store events.
• active: Production-ready. Can be triggered manually, through bulk actions, or automatically by configured Events.
• archived: Retired workflow. Remains visible in audit histories but cannot be executed by manual or automated triggers.

Trigger Mechanisms

Finqu supports three ways to invoke a Playbook:

1. Manual execution

Merchants trigger the playbook directly from Work Hub > Playbooks. The operator can provide optional runtime parameters (e.g. specifying a date range or selecting a target channel).

2. Bulk operations

Playbooks can be exposed as bulk actions in the Finqu admin. When a merchant selects multiple items in a table (e.g. 50 products or 20 unfulfilled orders) and selects Run Playbook, the playbook executes with the selected entity IDs injected into {{context.selected_ids}}.

3. Event triggers

Configure an Event to automatically start the playbook whenever a specific store event occurs or when a cron schedule fires:

{
  "event": "order_paid",
  "action": "run_playbook",
  "target_playbook": "post-purchase-vip-check"
}

Human-in-the-Loop Approval Gates

When a playbook modifies high-value store data (such as issuing refunds, deleting inventory, or publishing live pricing), configure a confirmation step with "require_approval": true.

When execution reaches an approval gate:

1. The playbook pauses and marks the run status as waiting_for_approval.
2. A notification appears in Work Hub and in the merchant’s activity feed showing the proposal.
3. The merchant can review the proposed changes, approve the run, or reject it with notes.
4. If approved, the subsequent Executor step runs immediately.

Next steps

• Authoring Workers — Define the specialized agents that power each step
• Events — Wire store actions and cron schedules to your Playbooks
• Inbound MCP Tools — Make external APIs available to Playbook steps
• Guidelines — Define global constraints and brand voice for Playbooks