Core Syntax Concepts

Merch Jar Formulas use a specific syntax to define logic for filtering data and creating custom calculations. Understanding these core components and terms is key to writing effective formulas.

Key Definitions

• Formula: The complete set of syntax written in the Composer, including variable definitions and a Formula expression, used to define a Segment.
• Composer: The editor interface within Merch Jar where you write and validate your Formula syntax.
• Segment: The resulting output table containing the items (e.g., Campaigns, Keywords) that match your Formula's filter criteria, along with any Custom Properties you defined.
• Workflow: A combination of an Action (like changing a bid or state) and a Schedule (like daily or manual) that can be applied to the items within a Segment. (Note: Currently, defining a Workflow is required when saving a Formula).
• Custom Property: A new, calculated data column that appears in your Segment results, defined within your Formula using the let keyword.

The Building Blocks of Formulas

Formulas combine several types of elements:

Properties

Represent data fields (like clicks, spend) or settings (like campaign name, bid) available within Merch Jar. They are the primary data points you'll filter or calculate with. Properties are either time-based or static.

• Time-based properties (e.g., sales, acos) measure performance over time and always require a Time Period specification enclosed in parentheses like (30d).
• Static properties (e.g., campaign name, bid) reflect current settings and do not use a Time Period.

See Properties Overview

Operators

Symbols or keywords used for comparison (>, =, contains), logic (and, or), or math (+, *). They define the relationship between properties and values.

See Built-ins Reference

Values

The specific numbers (10, 25%), text ("Brand Campaign"), or list items ("enabled") you compare properties against. String values must be quoted. Timestamp values typically result from date properties or the now() function.

Data Types

Every value has an underlying Data Type (Number, String, Timestamp, etc.). Comparisons and operations generally require compatible types.

See the Data Types Reference

Functions

Perform specific calculations or return dynamic values, like getting the current time (now()), implementing conditional logic (case()), or converting durations (interval()).

See Functions Overview

Variables

Used with the let keyword to define intermediate calculations or values within your formula, making complex logic easier to read and manage. These definitions also create Custom Properties. Variable names must start with a $ sigil and definitions must end with a semicolon ;.

Learn about Creating Custom Properties

Custom Properties

The named outputs created by let variable definitions. These appear as distinct columns in your resulting Segment table, showing the calculated value for each item that passes the filter. Underscores in the variable name (let $target_cpc = ...) are replaced with spaces in the column header (Target CPC).

Time Periods

Required for time-based properties to specify the date range (e.g., 30d, 7d..14d, YYYY-MM-DD..YYYY-MM-DD).

Learn about Using Time Periods

Grouping

Parentheses control the order in which complex logical (and/or) or mathematical expressions are evaluated.

Learn about Boolean Logic & Grouping

Comments

Add explanatory notes within your formula that are ignored by the system.

Learn about Adding Comments

Formula Structure

A Formula consists of two main parts:

1. (Optional) Variable Definitions: Zero or more variable definitions using the let function, each ending in a semicolon (;), creating Custom Properties.
2. (Required) Formula Expression: A single boolean expression (evaluates to true or false) that determines which items are included in the Segment. Even if you only want to calculate Custom Properties for all items, a filter expression like clicks(lifetime) >= 0 is currently needed.

// Part 1: Variable Definitions (creating Custom Properties)
let $avg_sales = sales(90d) / 3;
let $threshold = avg_sales * 0.9;

// Part 2: Formula Expressions (defining the Segment)
sales(30d) < $threshold

Next Steps

Now that you understand the basic structure, explore the specific components:

• Syntax Reference
• Using Time Periods
• Combining Conditions: Boolean Logic
• Creating Custom Properties

‍