Inventory Calculations

Configure intelligent inventory deduction rules using the Formula Builder to handle complex product configurations and material requirements.

Overview

TimberCloud's inventory calculation system allows you to define exactly how inventory should be deducted based on product configurations, dimensions, and options. This is essential for businesses that:

• Sell products by different units than they stock (e.g., sell by sqft, stock by sheet)
• Need to account for waste/yield in fabrication
• Have complex material requirements based on customer specifications

The same Formula Builder used for pricing works for inventory calculations — learn it once, use it everywhere.

Calculation Methods

TimberCloud supports three calculation systems (evaluated in priority order):

1. Step-Based Formula (Recommended)

The modern, visual approach using inventoryFormula:

• Build calculations step by step
• Use pre-built measurements
• Add conditional logic
• Same interface as pricing formulas

2. Flow-Based Formula (Legacy)

The visual flow builder using inventoryFlow:

• Node-based calculation design
• Still supported for backward compatibility
• Consider migrating to step-based

3. Calculation String (Legacy)

Raw JavaScript expressions using inventory_calculations:

• Direct code evaluation
• Most flexible but requires coding
• Legacy support only

Tip: New formulas should use the step-based Formula Builder. Legacy formulas continue to work but consider migrating for maintainability.

Step-Based Formula Builder

The formula builder uses an intuitive approach where you build calculations step by step.

Operand Types

Operators

How Formulas Are Stored

Formulas are stored on the Product Attribute in the inventoryFormula field:

{
  "stock_bf": {
    "steps": [
      { "type": "measurement", "measurementId": "board_feet" },
      { "type": "operator", "value": "*" },
      { "type": "field", "value": "qty" }
    ]
  }
}

Each key in the object corresponds to an inventory field name.

Available Measurements

Pre-built calculation formulas for common units:

Input Mapping

When using a measurement, you map which line item fields provide the inputs:

Measurement: Board Feet
  ├── thickness ← line item field "Thickness"
  ├── width ← line item field "Width"  
  └── length ← line item field "Length"

Configuring Formulas

Where to Configure

Inventory formulas are configured on the Product Attribute:

1. Go to Products → Attributes
2. Select your attribute
3. Find the Inventory Formula section
4. Click on an inventory field to configure its formula
5. Build your formula using the visual builder
6. Save

Mapping to Inventory Fields

Each formula is mapped to an inventory field name. This must match a part in your Product Attribute that has type "inventory":

Product Attribute: "Hardwood Lumber"
├── Stock BF (type: inventory)    ← inventory field
└── inventoryFormula: {
      "stock_bf": { ... formula ... }
    }

Common Patterns

Area-Based Calculations

For sheet goods, flooring, fabric, or panel products:

Scenario: Customer orders by square feet, you stock by sheet or unit.

Formula Steps:

1. Add Measurement → Square Feet
2. Map width and height to line item fields
3. Add Operator → × (multiply)
4. Add Field → qty

Result: Calculates total square feet ordered.

Linear Calculations

For trim, molding, lumber, or wire products:

Formula Steps:

1. Add Measurement → Linear Feet
2. Map length to line item field
3. Add Operator → × (multiply)
4. Add Field → qty

Result: Converts length from inches to feet and multiplies by quantity.

Volume Calculations

For concrete, mulch, gravel, or bulk materials:

Formula Steps:

1. Add Measurement → Cubic Feet
2. Map width, height, depth to line item fields
3. Add Operator → × (multiply)
4. Add Field → qty

Result: Calculates total cubic feet ordered.

Board Feet

For lumber inventory and sales:

Formula Steps:

1. Add Measurement → Board Feet
2. Map thickness, width, length to line item fields
3. Add Operator → × (multiply)
4. Add Field → qty

Result: Calculates board feet using the lumber industry standard formula.

Adding Waste Factors

Account for material waste in cutting, fabrication, or installation:

Static Multiplier

Add a fixed percentage waste:

1. Create your base calculation
2. Add Operator → × (multiply)
3. Add Number → 1.10 (for 10% waste)

Example: Square Feet × qty × 1.10

Waste Factor Measurement

Use the built-in waste calculation:

1. Add Measurement → Waste Factor
2. Map quantity field
3. Set waste percentage (e.g., 10)

Dynamic Waste with Conditionals

Different waste for different scenarios:

1. Add your base calculation
2. Add Operator → × (multiply)
3. Add Conditional:
   • If: width > 48
   • Then: 1.15 (15% waste for large panels)
   • Else: 1.10 (10% waste for standard)

Conditional Logic

Handle different scenarios with If/Then/Else:

Based on Dimensions

If width > 48
  Then: 1.15 (15% waste for large pieces)
  Else: 1.10 (10% waste for standard)

Based on Product Options

Access selected option values using dot notation:

If material.hardness > 5
  Then: 1.20 (20% waste for hard materials)
  Else: 1.10 (10% waste for soft materials)

Comparison Operators

Variables Available

Line Item Fields

Direct access to customer-entered values:

• qty — Quantity ordered
• width — Item width
• height — Item height
• depth — Item depth
• length — Item length
• Custom line item fields you've defined

Product Option Values

Access selected attribute values using dot notation:

attribute_name.part_name

Examples:

• material.thickness — Selected material's thickness value
• edge_banding.price_per_ft — Edge option's price
• finish.coverage_sqft — Finish coverage rate

Quick-Start Templates

The builder includes common formula templates:

Formula Examples

Plywood Sheets

Deduct sheets based on area (32 sqft per sheet):

Square Feet × qty ÷ 32

Lumber Boards

Calculate board feet for inventory:

Board Feet × qty

Edge Banding (per edge)

Calculate linear footage for edges:

Perimeter × qty ÷ 12

With Dynamic Waste

Panel cutting with size-based waste:

(Square Feet × qty) × (If width > 48 Then 1.15 Else 1.10)

Testing Calculations

Before Going Live

1. Save your formula
2. Create a test order with known dimensions
3. Verify the calculated deduction matches expected
4. Test edge cases:
   • Minimum values (qty = 1, small dimensions)
   • Maximum values (large orders)
   • Decimal values (10.5, 3.14)
   • Boundary conditions

Debugging Tips

1. Check field names — Ensure formula references match line item fields exactly
2. Verify mappings — Confirm measurement inputs map to correct fields
3. Test simple first — Start with basic formula, add complexity gradually
4. Log calculations — Check server logs for calculation debug output

Order Processing Flow

When an order is placed, inventory calculations execute automatically:

1. Order is created/confirmed
         ↓
2. For each order item:
   a. Get product attribute's inventoryFormula
   b. Build calculation context (line item values + options)
   c. Evaluate formula for each inventory field
   d. Calculate deduction amount
         ↓
3. Deduct from location inventory:
   a. Identify fulfillment location
   b. Find location inventory record
   c. Subtract calculated amount
   d. Update low stock status

Context Building

The calculation context includes:

• All line item field values (qty, width, height, etc.)
• All selected product option values (material.thickness, etc.)
• Numeric conversion of text values where possible

Legacy Support

Existing Formulas

If you have existing inventory calculations:

• Legacy formulas continue to work — No action required
• inventoryFlow (visual flow) is still evaluated
• inventory_calculations (code strings) are still supported

Migration Path

To update to step-based formulas:

1. Open the Product Attribute
2. Go to the inventory field's formula
3. Create a new step-based formula
4. Save — this overrides legacy configurations
5. Test thoroughly before relying on new formula

Priority Order

When multiple formula types exist, evaluation order is:

1. inventoryFormula (step-based) — Highest priority
2. inventoryFlow (visual flow) — Second priority
3. inventory_calculations (code string) — Fallback

Troubleshooting

Incorrect Results

• Verify formula logic step by step
• Check field mappings in measurements
• Confirm unit conversions are correct
• Review operator order — use groups if needed
• Check for rounding if precise values expected

Formula Not Working

• Ensure all inputs are mapped — Measurements need all inputs
• Check for empty fields — Missing values default to 0
• Verify formula has valid steps — At least one operand needed
• Test with simple known values first

Performance Issues

• Simplify complex calculations — Break into parts if needed
• Avoid deeply nested groups — Flatten when possible
• Use efficient patterns — Pre-built measurements are optimized

Best Practices

1. Start Simple: Begin with basic formulas, add complexity as needed
2. Use Measurements: Pre-built measurements handle unit conversions correctly
3. Test Thoroughly: Verify with real order scenarios before going live
4. Document Logic: Note why specific waste factors or multipliers are used
5. Group Complex Math: Use parentheses to ensure correct order of operations
6. Version Control: Keep track of formula changes for auditing

Related Topics

• Formula Builder — Complete formula builder documentation
• Inventory Overview — Inventory system introduction
• Inventory Management — Stock operations and tracking
• Parts — Configure product components