Formulas Syntax: Quickstart

This guide provides a rapid overview of the most common syntax patterns used in Merch Jar Formulas (V2) for users familiar with filtering, scripting, or formula concepts. For detailed explanations and full lists of properties, functions, and operators, please refer to the main Syntax Reference and related documentation pages.

1. Basic Filtering (Formula Expression)

‍Formulas end with a boolean expression to filter items.

// Static Property Comparison
state = "enabled"

// Time-based Property Comparison (Requires Time Period)
clicks(30d) > 10

2. Time-based vs. Static Properties

• Time-based properties (clicks, sales, acos, etc.) require (TimePeriod).
• Static properties (state, bid, campaign name, etc.) do not.

acos(14d) > 35%     // Correct: time-based with time period
bid > 0.50          // Correct: static without time period
// acos > 35%       // ERROR: Missing time period
// bid(14d) > 0.50  // ERROR: Time period on static property

3. Common Time Period Formats

Review the full guide on Using Time Periods for all options.

sales(7d)                          // Last 7 days
spend(30d..60d)                    // Period from 60 days ago through 30 days ago
orders(..)                         // All available data (same as 'lifetime')
clicks(2024-01-01..2024-01-31)     // Literal date range

4. Combining Conditions (and, or, ())

Use boolean operators and parentheses for complex logic. Learn more in Combining Conditions: Boolean Logic & Grouping.

clicks(7d) > 5 and orders(7d) > 0
state = "paused" or acos(30d) > 60%
(spend(14d) > 10 or clicks(14d) > 50) and state = "enabled"

5. Date & Timestamp Comparisons

‍Use now() for the current time and interval(Xd) for durations. See Functions Overview.

// Find items where bid hasn't changed in the last 7 days
last bid change < now() - interval(7d)

6. Variables & Custom Properties (let)

Define calculated values with let. Variable names must start with $ sigil and each definition ends with ; and creates a column in results. Read the full guide on Defining Variables & Custom Properties.

let $high_spend = 50.00;
let $target_rpc = 0.75;
let $current_rpc = sales(30d) / clicks(30d); // Requires handling division by zero in real use

spend(30d) > high_spend and current_rpc < target_rpc

7. Conditional Logic (case)

Implement if/then/else logic. Evaluates conditions sequentially and requires else. See Conditional Logic.

let $activity_level = case(
   clicks(7d) > 10 => "Medium",
   clicks (7d) > 20 => "High",
   else "Low"
);
‍
$activity_level != "Low"

8. Common Operators

Comparison: >, <, >=, <=, =, !=

Math: +, -, *, /

String: contains, does not contain, starts with, ends with

See the full Built-ins list in the Syntax Reference.

9. Comments

Use // for single-line comments and /*...*/ for block comments. See Adding Comments.

// Single-line comment
clicks(7d) > 0 // Check activity
‍
/*
This section identifies poorly performing keywords.
Criteria: No orders in 90 days despite significant spend.
*/

Putting It Together: Complete Example

Finding Neglected Keywords with Past Performance

Goal: Identify enabled keywords where the bid hasn't been adjusted recently (e.g., > 14 days), current clicks are low (e.g., < 5 in last 7 days), but which have generated orders at some point in their lifetime.

// --- Variables ---
‍
// Define how long ago the bid must have been changed to be considered "recent"
let $stale_bid_threshold_date = now() - interval("14d");

// Define the recent period for checking current low activity
let $recent_period = 7d;
let $low_click_threshold = 5;

// --- Final Filter Expression ---

// Find keywords that meet all criteria
last bid change < $stale_bid_threshold_date        // Bid is older than 14 days
and clicks($recent_period) < $low_click_threshold  // Recent clicks are low
and orders(lifetime) > 0                           // Keyword has generated orders historically
and state = "enabled"                              // Only consider enabled keywords

‍

Next Steps

• Explore the full Syntax Reference for all available properties, functions, and operators.
• Dive into specific topics like Time Periods, Variables, or Conditional Logic.
• See Example Formulas for more practical use cases.