Troubleshooting Bill Rate History

Overview

Bill Rate History stores Bill Rates on individual Punch and Paid Time Off (PTO) transactions. This allows historical reports and exports to continue using the Bill Rate associated with the transaction instead of automatically changing whenever an employee's current rate or a billing factor changes.

When investigating an unexpected Bill Rate, first determine:

  1. Whether Bill Rate History is enabled for the company.

  2. Whether the transaction already contains a stored Bill Rate.

  3. Which Bill Rate source the system should use.

  4. Whether the displayed result is an unresolved value, an explicit zero, or an output-specific formatting result.

  5. Whether the transaction should be preserved or intentionally recalculated.

Confirm the Company Settings

The Bill Rate History settings are available in the company's Timekeeper settings.

Keep Bill Rate History

This is the primary setting that activates historical transaction Bill Rates.

When enabled:

  • New Punch and PTO transactions can store regular, Overtime 1, and Overtime 2 Bill Rates.

  • Supported reports and exports use the normalized Bill Rate resolution process.

  • Bill Rate recalculation becomes available in TimeCard Tools.

When disabled:

  • The system does not normally capture automatic Bill Rate snapshots for new transactions.

  • Bill Rate-specific TimeCard Tools options are unavailable.

  • Existing employee Bill Rate functionality continues to operate according to the applicable report or export behavior.

The internal setting name may appear in technical logs or diagnostics as UseBillRates.

Update Bill Rate on PayRate Change

This setting controls normal transaction edits.

When enabled with Keep Bill Rate History:

  • An edit that updates or recalculates the transaction's Pay Rate also recalculates its Bill Rate.

  • Pay Rate processing occurs first.

  • Bill Rate is then determined from the resulting transaction Pay Rate and the current Bill Rate configuration.

When disabled:

  • Normal transaction edits preserve existing stored Bill Rates unless another explicit process replaces them.

The internal setting name may appear as UpdateRecordBillRatesOnChange.

This setting does not activate Bill Rate History by itself. Keep Bill Rate History is the authoritative setting.

Bill Rate Resolution Order

For a Bill-Rate-enabled company, the system resolves each Bill Rate component using the following priority:

  1. Stored transaction Bill Rate

  2. Employee Bill Rate

  3. Calculated Bill Rate

  4. Unresolved or blank

Regular, Overtime 1, and Overtime 2 Bill Rates are resolved independently. For example, a transaction may have a stored regular Bill Rate while its Overtime 1 Bill Rate is obtained from an employee rate or calculated fallback.

1. Stored Transaction Bill Rate

A Bill Rate saved directly on the Punch or PTO transaction has the highest priority.

This value is historical. It continues to be used even when the following later change:

  • Employee Bill Rate

  • Employee Pay Rate

  • Overtime billing factors

  • Tracking-level billing factors

  • Company settings

A different current employee rate is therefore not evidence that the historical transaction is incorrect.

2. Employee Bill Rate

When the transaction does not have a stored value, the system next checks the applicable employee Bill Rate.

Employee Bill Rates may include:

  • Regular Bill Rate

  • Overtime 1 Bill Rate

  • Overtime 2 Bill Rate

Employee Bill Rate access follows the existing Pay Rate security permissions. There is no separate Bill Rate permission.

3. Calculated Bill Rate

When neither a stored transaction value nor an employee Bill Rate is available, the system may calculate the Bill Rate using:

  • The effective Pay Rate stored on the transaction

  • The applicable billing factor

  • The applicable overtime rule or overtime billing factor

In simplified terms:

Calculated Bill Rate = Effective Transaction Pay Rate × Applicable Billing Factor

The calculation uses the transaction's effective Pay Rate rather than the employee's current Pay Rate whenever a usable transaction Pay Rate is available.

A missing, zero, or otherwise unusable Pay Rate does not automatically produce a calculated Bill Rate of zero. If the system cannot calculate a valid value, the Bill Rate remains unresolved.

4. Unresolved Bill Rate

A Bill Rate remains unresolved when no valid source is available.

Possible causes include:

  • No stored transaction Bill Rate

  • No applicable employee Bill Rate

  • No usable transaction Pay Rate

  • Missing billing-factor configuration

  • No applicable overtime configuration

  • An older transaction that was created before Bill Rate History was enabled

An unresolved Bill Rate is normally represented internally as a null value, not zero.

Blank and Zero Are Different

Support staff should distinguish between an unresolved Bill Rate and an explicit Bill Rate of zero.

Blank or Null

A blank value means the system could not resolve a Bill Rate.

This may be expected for:

  • Older transactions

  • Employees without Bill Rates

  • Transactions without usable Pay Rates

  • Missing factor configuration

Explicit Zero

A zero may be an intentionally stored or imported value.

An explicit zero is considered resolved. The system must not replace it with an employee rate or calculated fallback.

This distinction can affect:

  • Report grouping

  • Export formatting

  • Billing calculations

  • Troubleshooting results

Do not assume that 0.00 always means the transaction stored a zero. Some exports display unresolved values as 0.00 because of their output format.

Why a Historical Bill Rate Did Not Change

This is usually expected behavior.

When a transaction contains a stored Bill Rate, changing any of the following does not automatically rewrite it:

  • Employee Bill Rate

  • Employee Pay Rate

  • Billing factor

  • Overtime factor

  • Company Bill Rate settings

The stored transaction value remains the first source used by reports and exports.

To change historical Bill Rates, an authorized user must either:

  • Perform an edit that qualifies for recalculation while Update Bill Rate on PayRate Change is enabled, or

  • Use TimeCard Tools to intentionally recalculate Bill Rates.

Why a Bill Rate Changed After a Transaction Was Edited

Check Update Bill Rate on PayRate Change.

When this setting is enabled, edits that recalculate Pay Rate also recalculate Bill Rate. The new Bill Rate may differ because the current employee assignment, tracking levels, Pay Rate, overtime rule, or billing factors differ from those used when the transaction was originally created.

When this setting is disabled, normal edits should generally preserve the stored Bill Rate.

Also determine whether the user selected Adjust Bill Rate in TimeCard Tools. TimeCard Tools can intentionally overwrite historical snapshots regardless of normal edit preservation behavior.

Using TimeCard Tools

TimeCard Tools allows authorized users to recalculate Pay Rates and Bill Rates separately.

The Bill Rate option is available only when Keep Bill Rate History is enabled.

Adjust Pay Rate Only

This recalculates transaction Pay Rates while preserving existing Bill Rates.

Use this option only when Pay Rates need correction but historical Bill Rates should remain unchanged.

Adjust Bill Rate Only

This preserves transaction Pay Rates and recalculates Bill Rates from the existing effective transaction Pay Rates and current Bill Rate configuration.

Use this option when:

  • Pay Rates are already correct.

  • Employee Bill Rates or billing factors were corrected.

  • Historical Bill Rates need to be refreshed intentionally.

Adjust Pay Rate and Bill Rate

This is the normal combined option for correcting both sets of values.

The system:

  1. Recalculates Pay Rate.

  2. Uses the resulting transaction Pay Rate to recalculate Bill Rate.

When Pay Rate adjustment is selected for a Bill-Rate-enabled company, Bill Rate adjustment is selected by default.

Important Warning

TimeCard Tools intentionally rewrites selected historical values. Before proceeding, verify:

  • Company

  • Date range

  • Employee selection

  • Tracking-level filters

  • Pay Rate and Bill Rate selections

  • Locks and signoff status

  • Whether previously issued invoices or reports depend on the existing values

Historical recalculation should be performed only with customer approval.

Report and Export Differences

Supported reports and exports use the same general Bill Rate resolution priority, but unresolved values may be displayed differently.

Billing Summary

Expected behavior:

  • Uses resolved transaction Bill Rates for display and grouping.

  • An unresolved Bill Rate remains blank.

  • Required earnings calculations may still treat the unresolved value numerically without changing the displayed Bill Rate to zero.

Two otherwise similar transactions may appear in separate groups when their historical Bill Rates differ. This is expected.

DailyHours

In Billing Rate mode:

  • Resolved Bill Rates are used for grouping and output.

  • An unresolved regular Bill Rate is blank.

  • An explicit zero displays as 0.00.

  • Other numeric amount fields retain their existing output behavior.

Confirm that the report is running in the intended rate mode before comparing results.

PunchUpload

PunchUpload's Bill Rate field is defined as a Money field.

As a result:

  • A resolved Bill Rate is exported normally.

  • An unresolved Bill Rate is exported as 0.00.

  • An explicit zero is also exported as 0.00.

The output alone cannot distinguish an unresolved Bill Rate from an explicit zero. Inspect the underlying transaction and its available fallback sources.

PunchUpload must remain a 12-column pipe-delimited file in its existing column order.

Zenople

Expected behavior:

  • Uses the resolved Bill Rate for grouping and output.

  • An unresolved Bill Rate remains blank.

  • The related billing amount also remains blank when it cannot be determined.

  • An explicit zero remains a resolved value, although existing amount-formatting rules may suppress its display.

VoyantBeauty

Expected behavior:

  • Uses resolved Bill Rates for grouping.

  • An unresolved Bill Rate remains blank in the fixed-width Bill Rate field.

  • An explicit zero remains resolved internally.

  • Existing fixed-width zero-suppression formatting remains unchanged.

When investigating an apparent formatting issue, also verify the complete fixed-width record length and field positions.

Common Troubleshooting Scenarios

The Bill Rate Is Blank

Check the following in order:

  1. Is Keep Bill Rate History enabled?

  2. Does the transaction contain a stored Bill Rate?

  3. Does the employee have an applicable Bill Rate?

  4. Does the transaction contain a usable Pay Rate?

  5. Is the applicable billing factor configured?

  6. Is the correct overtime rule or PTO configuration available?

  7. Was the transaction created before Bill Rate History was enabled?

A blank value may be correct when none of the available sources can resolve a rate.

The Bill Rate Is Different From the Employee's Current Rate

Inspect the transaction's stored Bill Rate.

A stored transaction rate takes priority over the employee's current rate. This is the primary purpose of Bill Rate History and is normally expected behavior.

Also verify whether the transaction was imported with an explicit Bill Rate. Imported transaction Bill Rates, including explicit zero, take priority over automatic fallback behavior.

A New Transaction Did Not Store a Bill Rate

Verify:

  • Keep Bill Rate History was enabled when the transaction was created.

  • The transaction was created under the expected company.

  • The employee or transaction had sufficient information to resolve a rate.

  • The transaction's effective Pay Rate was usable.

  • Required billing factors were configured.

  • The transaction was created through a supported entry path.

  • No save, SQL, mapping, or concurrency error appears in the applicable logs.

Do not assume that every transaction must contain a value. An unresolved new transaction is stored as null rather than receiving a synthetic zero.

Regular Bill Rate Is Present but Overtime Is Blank

Regular, Overtime 1, and Overtime 2 values resolve independently.

Check:

  • Employee OT1 and OT2 Bill Rates

  • Effective OT1 and OT2 transaction Pay Rates

  • Overtime rule assignment

  • Overtime billing factors

  • Whether the transaction actually qualifies for the overtime component

  • Whether a stored value exists for that specific component

A regular rate does not guarantee that overtime rates can be resolved.

A Billing Factor Changed but Old Transactions Did Not

This is expected when the transactions contain stored Bill Rates.

Billing-factor changes affect:

  • Future transaction capture

  • Transactions without stored values that use calculated fallback

  • Historical transactions intentionally recalculated through an approved process

They do not automatically rewrite existing snapshots.

TimeCard Tools Does Not Show Adjust Bill Rate

Confirm that Keep Bill Rate History is enabled for the selected company.

Bill Rate recalculation is not available when the feature is disabled.

Also verify that the user has the required access and that the normal TimeCard Tools date, lock, signoff, and tracking-level restrictions are satisfied.

PunchUpload Shows 0.00 but Reports Show Blank

This can be expected.

PunchUpload converts an unresolved Bill Rate to 0.00 at the Money output boundary. Billing Summary, DailyHours, Zenople, and VoyantBeauty may preserve a blank value according to their individual output contracts.

Inspect the transaction to determine whether the underlying value is:

  • Explicit zero, or

  • Unresolved null

Historical Report Groups Changed

Historical Bill Rates can cause transactions to split into different report or export groups when their resolved Bill Rates differ.

This is expected and improves historical accuracy. Verify that the grouping difference corresponds to actual stored or resolved Bill Rate differences before treating it as a defect.

Suggested Diagnostic Process

Use the following sequence when reviewing a support case.

Step 1: Record the Context

Collect:

  • Company

  • Employee

  • Transaction type

  • Transaction date

  • Punch or PTO identifier

  • Regular, OT1, or OT2 component involved

  • Report or export name

  • Expected value

  • Actual displayed or exported value

Step 2: Check Company Configuration

Confirm:

  • Keep Bill Rate History

  • Update Bill Rate on PayRate Change

Record whether either setting changed after the transaction was created.

Step 3: Inspect the Transaction

Determine whether the relevant transaction Bill Rate component is:

  • A stored positive or negative value

  • Explicit zero

  • Null

Also inspect the corresponding transaction Pay Rate.

Step 4: Inspect Employee Rates

Review the applicable employee:

  • Regular Bill Rate

  • OT1 Bill Rate

  • OT2 Bill Rate

  • Pay Rates

  • Effective assignments and tracking levels

Step 5: Inspect Calculation Inputs

Verify:

  • Billing factor

  • Overtime billing factors

  • Overtime rule

  • PTO discriminator, when applicable

  • Tracking-level inputs

  • Effective transaction Pay Rate

Step 6: Compare With Resolution Priority

Determine which source should win:

  1. Transaction

  2. Employee

  3. Calculated

  4. Unresolved

Step 7: Account for Output Formatting

Determine whether the report or export converts an unresolved value to zero, preserves a blank, or suppresses zero for display.

Step 8: Decide Whether Correction Is Appropriate

Choose among:

  • No change; behavior is expected

  • Correct employee or factor configuration for future transactions

  • Edit the transaction under the approved recalculation setting

  • Use TimeCard Tools for an authorized historical recalculation

  • Escalate as a possible defect

When to Escalate

Escalate the issue to Development when the observed behavior does not match the documented resolution rules.

Examples include:

  • A stored transaction Bill Rate is ignored.

  • An explicit zero is replaced by an employee or calculated value.

  • A lower-priority source is used when a higher-priority value exists.

  • Bill Rates are captured while Keep Bill Rate History is disabled without an explicit imported value or another approved exception.

  • A normal edit changes a stored Bill Rate while Update Bill Rate on PayRate Change is disabled.

  • A qualifying edit fails to recalculate Bill Rate while the update setting is enabled.

  • Regular, OT1, or OT2 values overwrite one another.

  • A supported creation path consistently fails to capture resolvable Bill Rates.

  • TimeCard Tools recalculates in the wrong order.

  • An export changes its required column count, field order, record length, or formatting contract.

  • Save, SQL, mapping, or concurrency errors occur during transaction creation or editing.

Provide the diagnostic information collected above, along with relevant screenshots, output files, transaction identifiers, timestamps, and application logs.

Important Limitations

  • Existing transactions were not automatically backfilled when the feature was deployed.

  • A true historical Bill Rate cannot always be reconstructed when no historical snapshot exists.

  • Any customer-specific backfill or recalculation may be approximate unless an independent historical source is available.

  • Transaction-level Bill Rate fields are not currently exposed through every DTO or public API.

  • Manual release validation covered Timekeeper, DeskPunch, PINClock, and the supported WebConnect entry modes. Teams and physical clock paths were validated through automated coverage rather than the final manual acceptance pass.

Related Articles