
---

## In this article

* [Classic or advanced: choosing your approach](#classic-or-advanced-choosing-your-approach)
* [Set up classic recommendation logic](#set-up-classic-recommendation-logic)
* [Set up advanced recommendation logic](#set-up-advanced-recommendation-logic)
* [Handlebars quick reference](#handlebars-quick-reference)
* [After you save](#after-you-save)
* [Tips](#tips)


---

# What is recommendation logic?

Recommendation logic calculates suggested compensation values for every eligible employee in your merit cycle. You define the rules once, and the system applies them across your population. Recommendation logic can reference any data column in the cycle: performance ratings, band position, tenure, geography, business unit, custom columns your team uploads, or any combination. The examples in this article cover common patterns, but the system is designed to reflect whatever your organization's compensation philosophy requires.

Without recommendations, managers start from a blank input field for every employee. Recommendations anchor decisions to your compensation philosophy, reduce time per review, and keep outcomes consistent across managers.

 ![](https://support.pave.com/api/attachments.redirect?id=c3855aa1-3d91-42d7-8fab-d86a152aab26)

## How recommendations display

* Shown as floating text above the planner's input column, in local currency, company currency, or as a percentage
* Configured as a single target value or a min/target/max range
* Optionally prefilled into the input field so planners start from the suggested value
* Configured independently per pay type, so you can use different logic for salary raises and equity refreshers in the same cycle

 ![](https://support.pave.com/api/attachments.redirect?id=784ea21e-9e31-473b-b99f-cbadf5144780 " =1276x430")

## Prefilling recommendations

When configuring recommendation logic for any pay type, you can choose whether to prefill the input column with the recommended value. This controls how recommendations appear to planners:

* **Prefill off (default):** The recommendation appears as floating guidance text above the input field. Planners start from a blank input and can reference the recommendation as they decide.
* **Prefill on:** The input field is pre-populated with the recommended value. Planners can still override it, but the recommendation serves as the starting point rather than a reference.

Prefilling is useful when you want planners to start from the company's guidance and adjust only where needed, rather than building each decision from scratch.

## Recommendations, Smart Flags, and compensation controls

Recommendations are most powerful when paired with Smart Flags and compensation controls. Together, they form a complete governance loop:

* **Recommendations set the target.** They tell planners what the organization expects for each employee based on your compensation philosophy.
* **Smart Flags surface deviations.** Smart Flags are rule-based visual indicators that automatically highlight employee rows when specific conditions are met (for example, proposed salary falls outside the band, or a manager's pay is within 10% of a direct report). Flags can reference any column in the cycle, including recommendation outputs.
* **Compensation controls enforce boundaries.** Each smart flag can optionally carry a control: a **soft stop** requires the planner to add a justification comment before proceeding, while a **hard stop** blocks worksheet submission until the value is corrected or an authorized user overrides it.

**Example:** You set a 4% recommendation for "Meets expectations," attaches a smart flag that fires when a planner's input deviates from the recommendation by more than 1%, and adds a soft stop requiring the planner to explain why. Managers get clear guidance, the comp team gets visibility into every exception, and documentation happens automatically, with no manual review of hundreds of worksheets.

For more on Smart Flags and compensation controls, see [Smart Flags](smart-flags.md).

# Classic or advanced: choosing your approach

Both modes produce a recommended value per employee, but they differ in how you build the rules:

## **Classic** setup

Classic setup walks you through a guided flow: select a philosophy, define groupings, fill out a matrix. No formulas. Best when your rules map to performance ratings, band position, compa ratio, or geography.

## **Advanced** setup

Advanced setup opens a Handlebars code editor with syntax highlighting and a live preview panel. Select employees from the cycle to see calculated values update as you edit. Use this when your logic involves multi-factor calculations, conditional rules by business unit, or attributes not available in classic mode.

```
{{setVar "raisePercent" (inlineIf (eq columns.performanceRating "Exceeds expectations") 0.07 0.04)}}
{{setVar "rawRaise" (multiply columns.basePay (getVar "raisePercent"))}}
{{setVar "daysTenure" (dayDiff columns.startDate "2025-01-01")}}
{{setVar "prorationFactor" (min (divide (getVar "daysTenure") 365) 1)}}
{{min (multiply (getVar "rawRaise") (getVar "prorationFactor")) 15000}}
```

 ![](https://support.pave.com/api/attachments.redirect?id=d21c4470-4654-49f4-978f-35d7cad23496)

You can switch between classic and advanced at any time. Switching deletes the existing configuration for that column. Both modes can coexist across different pay types in the same cycle.


---

## Set up classic recommendation logic

### Select a pay type

Open the recommendation logic configuration page and select the pay type to configure. Pay types appear only when the corresponding column exists in the cycle. Select **Setup** to configure logic for a chosen program.

* **Salary raise:** Performance-based recommendations for non-promoted employees
* **Salary raise for promoted employees:** Separate logic or inherits from salary raise
* **Variable raise:** Maintains current pay mix, uses band targets, or a hybrid for promoted employees
* **New annual bonus:** Maintains the current bonus percentage as salary changes
* **Spot bonus:** Target bonus multiplied by optional company and individual performance multipliers
* **Equity refresher:** Target percentage multiplied by target equity on the current band (start date eligibility windows)
* **Equity promotion shares:** Percentage of promoted band target equity, or delta between promoted and current bands
* **Equity performance shares:** Target percentage multiplied by target equity for the current band (eligible ratings)
* **Market cash raise:** Different increases by metro, country, or flat rate
* **OTE pay mix:** Adjusts OTE-related compensation

### Choose a compensation philosophy

The philosophy determines your matrix structure.

**Salary raise:**

**Salary raise for promoted employees:**

**Market cash raise:**

### Configure dimensions

Depending on the philosophy, you configure one or more dimensions:

* **Performance ratings:** The rating values used in the cycle
* **Countries or metros:** Group locations so employees in the same group receive the same recommendation
* **Range penetration:** Breakpoints for position in band (for example, 0-25%, 25-50%, 50-75%, 75-100%)
* **Compa ratio:** Breakpoints for salary relative to market (for example, 0.80-0.90, 0.90-1.00, 1.00-1.10)

### Configure proration (optional)

Proration adjusts recommendations based on tenure. Set a proration end date and choose the reference point (start date or last compensation change).

`proration factor = (proration end date - reference date, in days) / 365`

The factor is always between 0 and 1. A 5% recommendation with a 0.504 factor becomes 2.52%.

### Fill out the recommendation matrix

Enter values in the matrix. You can enter a single target (5%) or a min/target/max range (3%-5%-7%).

### **Save and test**

Select **Save**, then open the worksheet to verify. To delete a configuration, select **Delete configuration** from the three-dot menu. Recommendation logic carries over when you duplicate a cycle.


---

 ![](https://support.pave.com/api/attachments.redirect?id=cb18e2e8-2a46-4b03-a066-4a5d80c59eef " =558x345")

## Set up advanced recommendation logic

### Select a pay type and choose advanced mode

Open the recommendation logic configuration, select the pay type, and choose

### Choose target only or range

* **Target only:** A single expression that calculates the recommended value
* **Range:** Three expressions (minimum, target, maximum). If you choose to prefill a  value, the target will be used

### Write your expressions

The code editor supports Handlebars expressions with syntax highlighting and inline error descriptions. Reference columns with `columns.<columnKey>`. Select **View column keys** for a searchable list of available columns.

See [Handlebars quick reference](#handlebars-quick-reference) for common patterns, or [Handlebars expression reference](handlebars-expression-reference.md) for the full function list.

Key rules:

* Expressions must evaluate to a number for currency and numeric columns
* Column keys are case-sensitive
* Use `coalesce` or `isNullOrUndefined` to handle columns that might be empty
* Circular references are not allowed

### Preview results

Select **Toggle employee preview** to see calculated values for specific employees in real time. Test with varied profiles: new hires, promoted employees, employees with missing data, different countries.

 ![](https://support.pave.com/api/attachments.redirect?id=520a6828-8faa-4565-a426-2ae0fd5e7fdc " =427x299")

### Save and configure prefilling

Select **Save**. Enable **Prefill target recommendations** to populate the worksheet automatically. Planners can still override prefilled values.


---

## Handlebars quick reference

Common patterns for advanced recommendation logic. Reference columns as `columns.<columnKey>`.

**Flat 5% salary raise:**

```
{{multiply columns.basePay 0.05}}
```

**Performance-based raise:**

```
{{#if (eq columns.performanceRating "Exceeds expectations")}}
  {{multiply columns.basePay 0.07}}
{{else if (eq columns.performanceRating "Meets expectations")}}
  {{multiply columns.basePay 0.04}}
{{else}}
  {{multiply columns.basePay 0.02}}
{{/if}}
```

**Promo bump on top of merit:**

```
{{add (multiply columns.basePay 0.03) (inlineIf (eq columns.isPromotion true) 5000 0)}}
```

**Raise capped at $15,000:**

```
{{min (multiply columns.basePay 0.08) 15000}}
```

**Band floor enforcement:**

```
{{max (multiply columns.basePay 0.03) (subtract columns.bandMin columns.basePay)}}
```

**Breaking complex logic into variables:**

```
{{setVar "merit" (multiply columns.basePay 0.04)}}
{{setVar "promo" (inlineIf (eq columns.isPromotion true) 5000 0)}}
{{add (getVar "merit") (getVar "promo")}}
```

**Null-safe column reference:**

```
{{multiply (coalesce columns.adjustedBase columns.basePay) 0.03}}
```

**Range (enter each in its own field):**

* Minimum: `{{multiply columns.basePay 0.02}}`
* Target: `{{multiply columns.basePay 0.05}}`
* Maximum: `{{multiply columns.basePay 0.08}}`

**Prorated raise based on start date:**

```
{{setVar "daysTenure" (dayDiff columns.startDate "2025-01-01")}}
{{setVar "prorationFactor" (min (divide (getVar "daysTenure") 365) 1)}}
{{multiply (multiply columns.basePay 0.05) (getVar "prorationFactor")}}
```

For the full function list, see [Handlebars expression reference](handlebars-expression-reference.md).


---

## After you save

**Audit logging:** All changes to recommendation logic are logged. View the audit trail from the recommendation configuration screen to see when changes were made and by whom.

**"Outside recommendations" filter:** The worksheet includes a quick filter that flags employees whose proposed compensation falls outside their recommendation, so you can spot where managers deviated from guidance.


---

## Tips

* **Start with classic** unless your logic needs formulas or conditions beyond what classic philosophies offer
* **Build advanced expressions incrementally.** Start simple, verify in the preview panel, then add complexity
* **Handle missing data.** Wrap column references in `coalesce` when a value might be empty, otherwise affected employees see no recommendation
* **Check range consistency.** Min should always be less than or equal to target, and target less than or equal to max
* **Promoted employee not seeing a recommendation?** The planner needs permission to view the promoted band. Check **Settings > Permissions**

Configure recommendation logic

Configurations overview

Cycle access permissions

Overview

Configure cycle settings

Configure employee eligibility

Configure approval chains

Configure cycle columns

Configure planning windows

Configure budgets

Configure worksheet settings

Configure currency and equity

Snapshot cycle data

Reset and delete cycles

Configure data upload

Configure reward letter settings

Cycle Setup

OTE planning

Writing formulas with Handlebars

Hourly and monthly pay

Custom Columns

Columns and Formulas

Using the planner worksheet

Using the employee detail view

Cycle Progress dashboard

Budgets dashboard

Cycle Outcomes dashboard

Approval Statuses 

Worksheet Experience

Overview of smart features in compensation planning

Peer Comparison

Smart Flags

Priority Sort

Compensation Outliers

Manager Compression Flag

Vesting Drop Flag

Flags and Insights

Compensation Planning

Connect ADP

Connect BambooHR

Connect Dayforce

Connect Deel

Connect Gusto

Connect HiBob

Connect Workday

Connect Namely

Connect Paylocity

Connect Personio

Connect Rippling

Connect UKG Pro

Connect CharlieHR

Connect Humaans

Connect Justworks

Connect Sapling

Connect SAP SuccessFactors

Connect TriNet

Connect Zenefits

HRIS Integrations

Connect Carta

Connect ComputerShare

Connect Shareworks

Connect E*Trade

Connect Fidelity

Connect Global Shares

Connect Pulley

Connect Schwab

Connect Ledgy

EMS integrations

Connect Culture Amp

Connect Workday Performance

Performance integrations

Connect Ashby

Connect Greenhouse

Connect Lever

Connect Workday ATS

ATS integrations

Manage your connections

Upload custom reports (historical pay, benefits, and original grant value)

Pave API

Send reward letters to Workday

Integrations

Configure Team View

Team View

Grades

Setting up Company Job Architecture

Company Job Architecture

Job Architecture 101

Pay Zone Manager

Step 1: Build Foundation

Generate Bands from Market Data

Editing Bands

Calculated Columns

Bands Set Audit Log

Bulk & Manually Associate Market Data to Bands

Employee Distribution in Bands

How to duplicate band sets

Managing & Reordering Calculated Columns

Unmatched Employees

View changes

Pay Types: Calculated TDC, Annual Equity, and Refresh Equity

Manually Create New Band Sets

Band Sets

Upload/Download Bands

Step 3: Update Ranges

Advanced Filters

Compare Bands

Generate Bands for New Jobs in Your Job Architecture

Relative Permissions

Ongoing Management & Analysis

Edit and apply benchmarks

Set weights and logic

Map data sources to jobs

Supported survey providers

Manage Pave data sources

Manage survey data sources

Benchmarks overview

Survey aging

Step 2: Benchmarking

Market Pricing

Create an account and log in

Set up single sign-on (SSO)

Account setup

Configure role permissions

Create and manage roles

Roles and permissions

Impersonate a user

Manage notifications

Complete your company profile

Manage company settings

Platform settings

Account & Permissions

June 2026 data release

Create and manage Peer Groups in Market Data

Create and manage Market Data reports

Equity data benchmarking

Explore data composition

Explore the Pave job catalog

Filter Market Data benchmarks

Get started with Market Data

Share Market Data externally

Use the Recent Hire filter

Market Data Benchmarks (Features & Workflows)

Understand Calculated Benchmarks

Understand Consistency Labels

Understand job matching

Understand Market Data methodology

Understand Job Levels

Market Data Methodology 

Explore Global Location Insights

Explore Equity Practices

Other Pave Market Data Products 

Market Data FAQ

FAQ's

Upgrade to Market Data Pro

Upgrades & Pricing 

Market Data

Customize branding in Total Rewards and Visual Offer Letter

Branding and customization

Configure benefits

Configure equity settings

Customize compensation display

Equity slider and valuation options

Compensation configuration

Future modeling overview

Configure future grant modeling

Configure compensation simulator

Future modeling

Set up Learning Hub content

Learning Hub

Total Rewards & Visual Offer Letter

Security at Pave

Security General Information

 Do you provide encrypted data storage of at least 256 AES?

Does Pave provide activity logs if requested? 

Will Pave connect a customer's data to any other systems?

Does Pave have a data retention policy? How long will the customer's data be kept in Pave's system?

What is Pave's threat detection strategy?

How do customers receive security alerts and/or security advisories?

Is Pave GDPR compliant?

What specific data is shared with Pave?

Can I please have your SOC 2 report?

Can people see our company name if we complete our integrations or is that also de-identified?

Can we complete the integration without sharing PII like employee name and email? 

How can I access Pave's DPA?

Are your data transmissions encrypted with at least TLS 1.2?

Security FAQs

Security

Guide

Pave

<p>Search for answers or submit a support ticket, right from the search bar.</p>