Formula Builder

The Formula Builder is a step-based visual editor used throughout TimberCloud for creating calculations without writing any code. You build a formula by adding steps — each step is a value (a field, a number, a named variable, a measurement, a group, or a conditional) — and connecting them with math operators. There is no JavaScript or code mode: you assemble everything visually.

Tip: Prefer plain English? The new AI Formula Assistant can write a step formula for you from a description like "material price per square foot plus $25 if the finish is Premium." See AI Formula Assistant below, or the full AI Pricing Assistant guide.

Overview

The same Formula Builder powers calculations across the platform:

Learn it once, use it everywhere. For pricing specifically, see Pricing.

Simple vs. Advanced mode

The pricing Formula Builder comes in two modes, and TimberCloud automatically opens whichever one fits your current formula. Both modes save the same underlying step formula — you can switch between them at any time.

Simple mode

A guided, strategy-first builder for the most common setups. Pick a strategy, fill in a field or two, and you're done — most products can be priced in under a minute. Simple mode offers four strategies:

Each strategy also offers an optional +/- markup adjustment to add or subtract a fixed amount or percentage on top.

Advanced mode

The full step-by-step builder described in the rest of this page: measurements, groups, named Variables, and multi-branch IF / ELSE IF / ELSE conditionals. Use it when you need tiered pricing, conditional surcharges, or reusable sub-calculations.

Switching modes

When you open a formula, the app picks the right mode for you. Inside the builder you'll see a Switch to Advanced link (in Simple mode) or Switch to Simple link (in Advanced mode). Simple formulas can always be promoted to Advanced; complex formulas open in Advanced automatically.

Getting Started

Accessing the Formula Builder

The builder opens from various locations depending on what you're calculating. The button is labeled Create Formula if no formula exists yet, or Edit Formula if you already have one:

• Pricing: Product → Pricing → Create Formula / Edit Formula (or the AI Assistant button)
• Parts: Product → Parts → a part dimension or quantity → Edit Formula
• Inventory: Product → Inventory → Create Formula
• Weight: Product → Parts → Weight → Calculation mode

Interface Overview

Operand Types

Each step in your formula uses one of these six operand types:

Field

Reference values from the order or product:

Line Items

• qty - Quantity ordered
• width - Item width
• height - Item height
• depth - Item depth/thickness
• length - Item length
• weight - Item weight

Product Options (Attributes)

• material.price - Selected material's price
• material.density - Material density value
• edge.upcharge - Edge option upcharge
• finish.name - Selected finish name

Field references use dot notation, auto-generated from your attribute names: attribute_name.property (for example design.stile_width or edge.lip_factor). The available fields are derived from the attributes you've set up on the product, so adding an attribute makes new fields available here.

Number (Static)

Enter fixed numeric values:

• Constants: 144 for square-inch conversion
• Multipliers: 1.10 for a 10% waste factor
• Base values: 25 for a base price
• Upcharges: 50 for an oversized fee

Variable

A named, reusable sub-calculation that you can reference elsewhere in the same formula as $name. Variables keep long formulas readable and let you compute something once and reuse it:

• Define a variable (for example $base = Square Feet × material.price)
• Reference it later in any step as $base
• Update the definition in one place and every reference follows

Variables appear with a teal $-prefixed badge in the preview. This is an Advanced-mode operand — it isn't available in Simple mode.

Measurement

Pre-built calculation blocks that automatically handle unit conversions. Pick a measurement and tell it which fields supply the inputs (width, height, thickness, etc.); the system does the rest:

Note: Lite Count, Glass Panels, and Lite Price Total are woodworking glass-door measurements. They read automatically from the product's glass/lite configuration; Lite Price Total additionally uses the lite pricing table defined on the product's Parts tab. They require that glass/lite config to be set up to return a value.

Group

Create parentheses for order of operations:

• Contains its own nested steps
• Essential for calculations like (A + B) × C
• Ensures correct mathematical precedence

Conditional (IF / ELSE IF / ELSE)

Add logic-based calculations with one or more branches:

• IF — the first condition; if it's true, its value is used
• ELSE IF — add as many additional conditions as you need, each evaluated in order
• ELSE — the fallback value used when none of the conditions match

Each branch's "then" value can be any step or group, so you can return a full sub-calculation, not just a number. This multi-branch format makes tiered pricing easy — no deeply nested conditionals required.

Conditions support these comparison operators:

Operators

Connect steps with mathematical operators:

Building Formulas

Step-by-Step Process

1. Click "Add Step" or start with a template
2. Select operand type (Field, Number, Variable, Measurement, Group, or Conditional)
3. Configure the operand (select a field, enter a value, define a variable, or set up a measurement)
4. Add another step if needed
5. Select operator between steps (+, −, ×, ÷)
6. Repeat until the formula is complete
7. Review the preview to verify the formula
8. Save to apply

Common Formula Templates

Templates vary by context but typically include:

Pricing Templates

• Price per Square Foot
• Price per Board Foot
• Base + Per-unit pricing
• Tiered quantity pricing

Inventory Templates

• Quantity Only
• Board Feet × Quantity
• Square Feet × Quantity
• Field × Quantity

Part Dimension Templates

• Width + Overlay
• Height minus rail widths
• Calculated from line item

Formula Examples

Example 1: Pricing — Cabinet Door

Calculate door price based on square feet, material, and edge banding:

Square Feet(width, height) × material.price
+ Perimeter(width, height) × edge.price
+ IF width > 48 THEN 50 ELSE 0

Steps:

1. Measurement: Square Feet → width, height
2. Operator: ×
3. Field: material.price
4. Operator: +
5. Measurement: Perimeter → width, height
6. Operator: ×
7. Field: edge.price
8. Operator: +
9. Conditional: IF width > 48 THEN 50 ELSE 0

Example 2: Inventory — Sheet Goods with Waste

Calculate material deduction including 10% waste:

Square Feet(width, height) × qty × 1.10

Steps:

1. Measurement: Square Feet → width, height
2. Operator: ×
3. Field: qty
4. Operator: ×
5. Number: 1.10

Example 3: Part Dimension — Rail Length

Calculate rail length based on door width minus stiles:

width - (stile_width × 2) + lip_factor

Steps:

1. Field: width
2. Operator: −
3. Group:
   • Field: design.stile_width
   • Operator: ×
   • Number: 2
4. Operator: +
5. Field: edge.lip_factor

Example 4: Weight — Calculated from Density

Calculate part weight from volume and material density:

Cubic Feet(width, height, depth) × material.density

Steps:

1. Measurement: Cubic Feet → width, height, depth
2. Operator: ×
3. Field: material.density

Example 5: Glass-Door Pricing — Lite Count

Add a per-lite charge to a glass cabinet door:

Square Feet(width, height) × material.price
+ Lite Count × 6

Steps:

1. Measurement: Square Feet → width, height
2. Operator: ×
3. Field: material.price
4. Operator: +
5. Measurement: Lite Count
6. Operator: ×
7. Number: 6

If you've configured a lite pricing table on the Parts tab, you can use the Lite Price Total measurement directly instead of multiplying by a flat per-lite rate.

Example 6: Reusable Variable

Compute a base price once with a Variable, then reuse it:

$base = Square Feet(width, height) × material.price
$base + IF finish.name is "Premium" THEN $base × 0.15 ELSE 0

Steps:

1. Define Variable $base: Square Feet × material.price
2. Field/Variable: $base
3. Operator: +
4. Conditional: IF finish.name is "Premium" THEN ($base × 0.15) ELSE 0

Advanced Features

Nested Groups

Create complex order of operations:

Formula: (base + material) × (1 + margin)

Group 1: (base_price + material.price)
×
Group 2: (1 + margin_percent)

Multi-branch Conditionals

Handle multiple tiers in a single conditional using IF / ELSE IF / ELSE branches:

IF qty >= 100 THEN
  price × 0.85
ELSE IF qty >= 50 THEN
  price × 0.90
ELSE IF qty >= 25 THEN
  price × 0.95
ELSE
  price

Combining Measurements

Use multiple measurements in one formula:

Square Feet × price_per_sqft
+ Perimeter × edge_price
+ Cubic Feet × shipping_factor

AI Formula Assistant

The AI Formula Assistant lets you describe pricing in plain English and have the assistant build the step formula for you. It produces the exact same step-based formula the builder uses — there's no separate "AI formula" format — so anything it generates is fully editable in the builder afterward.

Where to find it

On the product Pricing panel, click the AI Assistant button (marked with a Sparkles icon) next to Create Formula / Edit Formula.

How it works

1. Describe the pricing in plain English — for example:
   • "Charge the material price per square foot, plus $25 if the finish is Premium."
   • "Tiered quantity pricing: $35/sq ft under 25 units, $30 from 25–99, $28 for 100+."
   • "Add a 10% rush surcharge." (when editing an existing formula)
   • "Change the rate to $60 per square foot."
2. Generate. The assistant returns the proposed formula along with a plain-language explanation and any warnings (for example, if a field it referenced doesn't exist on the product yet).
3. Choose an action:
   • Accept — apply the generated formula directly.
   • Edit Manually — drop the generated formula into the Advanced Formula Builder so you can fine-tune it step by step.
   • Revise — refine it conversationally ("make the surcharge 15% instead"); the assistant keeps the context of your previous request.

The assistant works for both creating a new formula and editing an existing one — just describe the change you want. AI is included on Commerce and up (no separate metered add-on).

For a deeper walkthrough, example prompts, and the result panel, see the AI Pricing Assistant guide and the AI overview.

Formula Preview

The preview displays your formula visually:

Use the preview to verify your formula structure before saving.

Context-Specific Usage

Pricing Formulas

• Access from Product → Pricing
• Result becomes the line item unit price
• Multiplied by quantity for the line total
• See Pricing for detailed examples, and AI Pricing Assistant for the plain-English path

Part Dimension Formulas

• Access from Product → Parts → Dimension specs
• Calculate width, length, height, depth
• Used in build sheets and shipping
• See Parts for configuration

Part Quantity Formulas

• Access from Product → Parts → Quantity
• Determine how many of each part per product
• Can be static, field-based, or calculated
• Example: height / 12 for one brace per foot

Part Weight Formulas

• Access from Product → Parts → Weight
• Calculate weight from dimensions and density
• Used for accurate shipping rates
• Example: Cubic Feet × density

Inventory Formulas

• Access from Product → Inventory
• Calculate material deduction on order
• Supports waste factors and conversions
• See Inventory Management for details

Legacy Support

If you have existing calculations from an older configuration (the legacy pricing code or visual flow), they continue to work — but they are backend-only fallbacks, not editors you author in today. The step-based Formula Builder (and AI Assistant) is the only authoring surface in the app.

• Legacy formulas continue to work — the backend evaluates them normally for older products
• A yellow banner indicates a legacy configuration is active on a product
• Creating a new step formula overrides the legacy configuration — the moment you save a step formula, it takes priority
• Migration recommended for consistency and easier editing going forward

There is no longer a JavaScript code editor or a drag-and-drop node/flow builder for pricing in the app — those legacy mechanisms only evaluate on the backend for old products.

Best Practices

Keep It Simple

• Try Simple mode first — most products only need a strategy and a field or two
• Break complex formulas into logical Groups
• Use named Variables to avoid repeating the same sub-calculation
• Use descriptive attribute names so your field references are readable
• Test with known values

Use Templates and AI

• Start with a common formula template when available
• Or describe the pricing to the AI Formula Assistant and refine the result
• Modify a starting point rather than building from scratch

Order of Operations

• Use Groups (parentheses) to ensure the correct order
• Preview the formula to verify its structure
• A + B × C is different from (A + B) × C

Testing

1. Save the formula
2. Create a test order with known values
3. Verify the calculated result
4. Adjust the formula as needed

Troubleshooting

Formula Not Saving

• Ensure all required inputs are configured
• Check for empty field selections in measurements
• Verify the formula has at least one step
• Look for validation errors in the UI

Wrong Results

• Check field mappings in measurements
• Verify operator order (use Groups if needed)
• Test with known values to isolate issues
• Confirm field names match exactly

Field Not Available

• Verify the attribute or line item exists on the product
• Check that spelling matches exactly (field names are case-sensitive)
• Ensure the attribute has the property you're referencing
• A referenced Variable must be defined before it can be used as $name

Lite / Glass Measurement Returns Zero

• Confirm the product has glass/lite configuration set up
• For Lite Price Total, make sure the lite pricing table is configured on the Parts tab

Legacy Formula Conflicts

• Look for the yellow "Legacy Configuration" banner
• Create a new step-based formula to override it
• Legacy formulas are evaluated on the backend only

Next Steps

• Pricing - Create product pricing formulas
• AI Pricing Assistant - Generate formulas from plain English
• Parts - Configure part dimensions and quantities
• Build Sheet Builder - Create production documents
• Inventory Management - Track stock and deductions