Core Concepts

Understanding the fundamental building blocks of Function Lab.

Overview

Function Lab configurations consist of rules that evaluate conditions and execute events. Optional facts enable complex data transformations.

Input Data → Facts → Conditions → Events → Output

Rules

A rule is the basic unit of logic in Function Lab.

Structure

{
  "rules": [
    {
      "facts": { /* optional data transformations */ },
      "conditions": { /* when to apply this rule */ },
      "events": [ /* what to do when conditions match */ ]
    }
  ]
}

Required Fields

conditions: Object defining when the rule applies
events: Array of actions to take when conditions are met

Optional Fields

facts: Named calculations for reuse in conditions and events
if-not-events: Alternative events when conditions don’t match

Conditions

Conditions determine when a rule should fire. They query the input data using dot notation and predicates.

Simple Condition

{
  "conditions": {
    "customer.tags": {
      "includes": "VIP"
    }
  }
}

Checks if customer tags array includes “VIP”.

Multiple Conditions (AND)

{
  "conditions": {
    "customer.tags": {
      "includes": "VIP"
    },
    "cart.totalAmount": {
      "gte": 100
    }
  }
}

Both conditions must be true (implicit AND).

OR Logic

{
  "conditions": {
    "or": [
      { "customer.tags": { "includes": "VIP" } },
      { "customer.tags": { "includes": "WHOLESALE" } }
    ]
  }
}

Available Predicates

Predicate	Description	Example
`equal`, `eq`, `is`	Exact match	`"customer.email": { "is": "user@example.com" }`
`includes`, `contains`	Array contains value	`"customer.tags": { "includes": "VIP" }`
`gt`, `greater`	Greater than	`"cart.totalAmount": { "gt": 100 }`
`gte`, `greaterEq`	Greater than or equal	`"cart.totalAmount": { "gte": 100 }`
`lt`, `less`	Less than	`"cart.lineCount": { "lt": 5 }`
`lte`, `lessEq`	Less than or equal	`"cart.lineCount": { "lte": 10 }`
`exists`	Field exists	`"customer.id": { "exists": true }`
`empty`	Array/string is empty	`"customer.tags": { "empty": false }`

See Predicates Reference for complete list.

Events

Events define what happens when conditions match. Event structure depends on the function type.

Product Discount Event

{
  "events": [
    {
      "discount": "product_discount",
      "params": {
        "discount_type": "percentage",
        "value": 15,
        "message": "15% Off Sale"
      }
    }
  ]
}

Multiple Events

A rule can have multiple events:

{
  "events": [
    {
      "discount": "product_discount",
      "params": {
        "handles": ["t-shirt"],
        "discount_type": "percentage",
        "value": 20,
        "message": "20% off T-Shirts"
      }
    },
    {
      "discount": "product_discount",
      "params": {
        "handles": ["jeans"],
        "discount_type": "percentage",
        "value": 15,
        "message": "15% off Jeans"
      }
    }
  ]
}

Facts

Facts are named calculations that transform input data for reuse in conditions and events.

Basic Fact

{
  "facts": {
    "total_quantity": "cart.lines[].quantity | sum(@)"
  },
  "conditions": {
    "$total_quantity": { "gte": 10 }
  }
}

The $ prefix references a fact in conditions.

Why Use Facts?

Reusability: Calculate once, use everywhere
Readability: Name complex expressions
Performance: Avoid redundant calculations
Power: Use JMESPath or custom filters for complex queries

Example: Collection Filtering

{
  "facts": {
    "sale_items": "cart.lines[?merchandise.product.collections[?handle=='sale']].id"
  },
  "conditions": {
    "$sale_items": { "empty": false }
  },
  "events": [
    {
      "discount": "product_discount",
      "params": {
        "selector": "$sale_items",
        "discount_type": "percentage",
        "value": 25,
        "message": "25% off Sale Items"
      }
    }
  ]
}

See Facts System for deep dive.

Input Data Structure

Function Lab receives cart and customer data from Shopify in a standardized format:

{
  "cart": {
    "lines": [
      {
        "id": "gid://shopify/CartLine/...",
        "quantity": 2,
        "merchandise": {
          "id": "gid://shopify/ProductVariant/...",
          "title": "Size M",
          "product": {
            "id": "gid://shopify/Product/...",
            "title": "Cool T-Shirt",
            "handle": "cool-t-shirt",
            "vendor": "Awesome Brand",
            "collections": [...]
          }
        }
      }
    ],
    "totalAmount": 100.00,
    "buyerIdentity": {
      "customer": {
        "id": "gid://shopify/Customer/...",
        "email": "customer@example.com",
        "tags": ["VIP", "WHOLESALE"]
      }
    }
  }
}

See Input Structure Reference for complete schema.

Path Notation

Access nested data using dot notation:

Path	Accesses
`customer.email`	Customer’s email address
`customer.tags`	Array of customer tags
`cart.lines`	Array of cart line items
`cart.lines[].merchandise.product.handle`	Product handles for all lines

Array Access

Arrays are automatically traversed:

{
  "customer.tags": { "includes": "VIP" }
}

Checks if any tag equals “VIP” (automatic ANY semantics).

Execution Flow

Input Received: Shopify sends cart/checkout data
Facts Computed: Named calculations evaluated once
Conditions Evaluated: Check if rule should fire
Events Executed: Generate discounts/operations
Output Returned: Results sent back to Shopify

Next Steps

How It Works - Detailed execution model
Testing - Test and debug your functions
Common Patterns - Real-world examples
Function Types - Explore specific function types

Getting Started

Function Types

Advanced Features

Core concepts

Core Concepts

Overview

Rules

Structure

Required Fields

Optional Fields

Conditions

Simple Condition

Multiple Conditions (AND)

OR Logic

Available Predicates

Events

Product Discount Event

Multiple Events

Facts

Basic Fact

Why Use Facts?

Example: Collection Filtering

Input Data Structure

Path Notation

Array Access

Execution Flow

Next Steps

​Core Concepts

​Overview

​Rules

​Structure

​Required Fields

​Optional Fields

​Conditions

​Simple Condition

​Multiple Conditions (AND)

​OR Logic

​Available Predicates

​Events

​Product Discount Event

​Multiple Events

​Facts

​Basic Fact

​Why Use Facts?

​Example: Collection Filtering

​Input Data Structure

​Path Notation

​Array Access

​Execution Flow

​Next Steps

Core Concepts

Overview

Rules

Structure

Required Fields

Optional Fields

Conditions

Simple Condition

Multiple Conditions (AND)

OR Logic

Available Predicates

Events

Product Discount Event

Multiple Events

Facts

Basic Fact

Why Use Facts?

Example: Collection Filtering

Input Data Structure

Path Notation

Array Access

Execution Flow

Next Steps