Payment Application Variables

Include variables from this article in a document template to populate values from the payment application in the system. For example, you can add the payment application's number, description, or the original contract value.

In this article:

To learn more about:

Common Use Cases and Examples

Before diving into the complete variable reference, here are practical examples for the most common scenarios:

Payment Application Header

Create a professional header for your payment application documents:

PAYMENT APPLICATION #{payment.number}
Contractor: {payment.supplier}
Project: {payment.name}
Billing Period: {payment.startDate | date: "%B %d, %Y"} to {payment.endDate | date: "%B %d, %Y"}

Approval History Summary

Track who approved what and when for audit requirements:

APPROVAL HISTORY:
{#approvalHistories}
• {stepName}: {action} by {operator.name}
{/approvalHistories}

Financial Summary

Display key financial totals at a glance:

Original Contract Amount: {payment.contractAmount | currency}
Total Change Orders: {payment.totalApprovedChangeOrders | currency}
Contract Sum to Date: {payment.contractSumToDate | currency}
Current Payment Due: {payment.currentPayment | currency}
Balance to Finish: {payment.balanceToFinish | currency}

Line Item Table

Generate detailed line items for work completed:

{#payment.columnView.items}
{number} | {name} | {originalAmount | currency} | {amount | currency} | {percentCompleted}%
{/payment.columnView.items}

TOTALS:
Work Completed: {payment.columnView.totalAmount | currency}
Materials Stored: {payment.columnView.totalMaterialsStored | currency}
Total Retention: {payment.columnView.totalRetainage | currency}

Previous vs Current Comparison

Show progress from previous payment application:

Previous Payment #{previousPayment.number}: {payment.previousPayment | currency}
Current Period Work: {payment.currentPayment | currency}
Total Earned to Date: {payment.totalEarned | currency}

Materials Billed Tracking

When Materials Billed setting is enabled, track materials delivered to the job site:

Materials Delivered This Period: ${payment.lineView.materialsBilled | currency}
Materials Delivered Previously: ${payment.lineView.previousMaterialsBilled | currency}
Total Materials Delivered: ${payment.lineView.materials | currency}

Calculation: {payment.lineView.materials} = {payment.lineView.previousMaterialsBilled} + {payment.lineView.materialsBilled}

This replaces the need to manually calculate totals using the previously available totalMaterialsStored variable.

Change Order Summary with Additions and Deductions

Separate positive and negative change orders into distinct columns:

CHANGE ORDER SUMMARY
                     Additions    Deductions
Previous Periods:    {payment.approvedChangeOrderAdditionsInPreviousPeriod | currency}    {payment.approvedChangeOrderDeductionsInPreviousPeriod | currency}
This Period:         {payment.approvedChangeOrderAdditionsThisPeriod | currency}    {payment.approvedChangeOrderDeductionsThisPeriod | currency}
TOTALS:              {payment.totalApprovedChangeOrderAdditions | currency}    {payment.totalApprovedChangeOrderDeductions | currency}
Net Change Orders: {payment.totalApprovedChangeOrders | currency}

Tips for Using Variables

Supplier-Specific Values

Tip:

You can precede any payment application variable with contract.supplier. to return values specific to the supplier.

Example: {contract.supplier.payment.currentPayment}

Spreadsheet Compatibility

Important:

Spreadsheets can't support rich text variables. Remove the "@" symbol when using variables in spreadsheets.

Instead of: {@pco.scopeOfWork}
Use: {pco.scopeOfWork}

Line Mode vs Column Mode

Note:

If you're using line mode (Show change orders as line items) on the payment application, replace columnView with lineView in your variables.

Column Mode: {payment.columnView.totalAmount}
Line Mode: {payment.lineView.totalAmount}

Change Order Addition/Deduction Variables

Important:

These variables do not support inline mode and require fully approved change orders for accuracy.

Complete Variable Reference

Use the search at the top of the table to narrow down results. Variables are organized by category for easier navigation.

Variables Description Type
BASIC INFORMATION
{payment.number} Returns the payment application number. String
{payment.name} Returns the payment application name. String
{payment.description} Returns the payment application description. String
{payment.supplier} Returns the supplier's company. String
{payment.owner} Returns the owner's company. String
{payment.architect} Returns the architect's company. String
{@payment.note} Returns the payment application note. RichText
APPROVAL WORKFLOW
{#approvalHistories} and {/approvalHistories} Returns the approval history details of the payment application including action taken, workflow step name, and operator name.

Use {#approvalHistories} and {/approvalHistories} together.

 Array
{#approvalHistories.action}

For example:
{#approvalHistories}{action}

{/approvalHistories}

 Returns the action taken in the approval workflow step. String
{#approvalHistories.stepName}

For example:
{#approvalHistories}{stepName}

{/approvalHistories}

 Returns the workflow step name in the approval history. String
{#approvalHistories.operator.name}

For example:
{#approvalHistories}{operator.name}

{/approvalHistories}

 Returns the name of the person who performed the approval action. String
DATES & TIMELINE
{payment.startDate} Returns the billing period start date of the payment application. Date
{payment.endDate} Returns the billing period end date of the payment application. Date
{payment.createdAt} Returns the date when the payment application was created. Date
{payment.submittedAt} Returns the date when the payment application was submitted. Date
{payment.revisedAt} Returns the date when the payment application was revised. Date
{payment.updatedAt} Returns the date when the payment application was updated. Date
CORE FINANCIAL TOTALS
{payment.contractAmount} Returns the original contract value of the payment application. Number
{payment.contractSumToDate} Returns the contract sum to date. Number
{payment.totalCompletedAndStored} Returns the total work completed and stored material to date. Number
{payment.totalEarned} Returns the total earned less retainage. Number
{payment.previousPayment}
For example:

{#payment.previousPayment == ""} {/} {#payment.previousPayment < 0} ({payment.previousPayment | multiply: -1}) {/}

 Returns the total earned less retainage from previous payment application. Number
{payment.currentPayment} Returns current payment due. Number
{payment.balanceToFinish} Returns balance to finish including the retainage. Number
RETENTION & RETAINAGE
{payment.completedWorkRetentionPercent} Returns the percentage of total work completed and stored material to date. Number
{payment.completedWorkRetention} Returns the retention amount of completed work. Number
{payment.materialsOnStoreRetentionPercent} Returns the percentage of retention of materials on site. Percent
{payment.materialsOnStoreRetention} Returns the number of materials retained on site. Number
{payment.allTotalRetainage} Returns the total retention amount. Number
{payment.previousCompletedWorkRetained} Returns the retained amount from completed work from previous payment applications. Number
{payment.previousMaterialsRetained} Returns the retained amount from materials stored from previous payment applications. Number
{payment.currentCompletedWorkRetention} Returns the current period retention amount for completed work. Number
{payment.currentMaterialsRetention} Returns the current period retention amount for materials stored. Number
{payment.thisPeriodRetainage} Returns the current payment's total retainage minus the previous payment's retainage. Number
CHANGE ORDERS & VARIATIONS
{payment.approvedInPreviousPeriod} Returns the total variations approved in previous period. Number
{payment.approvedThisPeriod} Returns the total variations this period. Number
{payment.totalApprovedChangeOrders} Returns the net changes by Change Order. Number
{payment.approvedChangeOrderAdditionsInPreviousPeriod} Returns the total approved change order additions from previous periods. Number
{payment.approvedChangeOrderDeductionsInPreviousPeriod} Returns the total approved change order deductions from previous periods. Number
{payment.approvedChangeOrderAdditionsThisPeriod} Returns the approved change order additions for this period. Number
{payment.approvedChangeOrderDeductionsThisPeriod} Returns the approved change order deductions for this period. Number
{payment.totalApprovedChangeOrderAdditions} Returns the total approved change order additions across all periods. Number
{payment.totalApprovedChangeOrderDeductions} Returns the total approved change order deductions across all periods. Number
LINE ITEM DETAILS
{#payment.columnView.items} and {/payment.columnView.items} Returns the item details of the payment application when OCOs are displayed as a column.

Use {#payment.columnView.items} and {/payment.columnView.items} together.

 Array
{#payment.columnView.items.number}

For example:
{#payment.columnView.items}{number}

{/payment.columnView.items}

 Returns the line item number of the payment application. String
{#payment.columnView.items.name}

For example:
{#payment.columnView.items}{name}

{/payment.columnView.items}

 Returns the line item name of the payment application. String
{#payment.columnView.items.originalQuantity}

For example:
{#payment.columnView.items}{originalQuantity}

{/payment.columnView.items}

 Returns the line item original quantity of the payment application. Number
{#payment.columnView.items.unit}

For example:
{#payment.columnView.items}{unit}

{/payment.columnView.items}

 Returns the line item unit of the payment application. String
{#payment.columnView.items.originalUnitPrice}

For example:
{#payment.columnView.items}{originalUnitPrice}

{/payment.columnView.items}

 Returns the line item original unit price of the payment application. Number
{#payment.columnView.items.originalAmount}

For example:
{#payment.columnView.items}{originalAmount}

{/payment.columnView.items}

 Returns the line item original schedule of value of the payment application. Number
{#payment.columnView.items.changeOrders}

For example:
{#payment.columnView.items}{changeOrders}

{/payment.columnView.items}

 Returns the line item of change orders' value of the payment application. Number
{#payment.columnView.changeOrderQuantity} Returns change orders' quantity. Number
{#payment.columnView.items.revisedQuantity}
For example:
{#payment.columnView.items}{revisedQuantity}
{/payment.columnView.items}		 Returns the line item revised quantity of the payment application. Number
{#payment.columnView.items.revisedValue}

For example:
{#payment.columnView.items}{revisedValue}

{/payment.columnView.items}

 Returns the line item of revised value of the payment application. Number
{#payment.columnView.items.previousQuantity}

For example:
{#payment.columnView.items}{previousQuantity}

{/payment.columnView.items}

 Returns the line item of quantity of the previous payment application. Number
{#payment.columnView.items.previousAmount}

For example:
{#payment.columnView.items}{previousAmount}

{/payment.columnView.items}

 Returns the line item of work completed value of the previous payment application. Number
{#payment.columnView.items.quantity}

For example:
{#payment.columnView.items}{quantity}

{/payment.columnView.items}

 Returns the line item of quantity of the current payment application. Number
{#payment.columnView.items.amount}

For example:
{#payment.columnView.items}{amount}

{/payment.columnView.items}

 Returns the line item of work completed value of the current payment application. Number
{#payment.columnView.items.materialsOnStoreQuantity}

For example:
{#payment.columnView.items}{materialsOnStoreQuantity}

{/payment.columnView.items}

 Returns the line item quantity of materials stored value of the payment application. Number
{#payment.columnView.items.materialsOnStoreUnitPrice}

For example:
{#payment.columnView.items}{materialsOnStoreUnitPrice}

{/payment.columnView.items}

 Returns the line item unit price of materials stored value of the payment application. Number
{#payment.columnView.items.materialsStored}

For example:
{#payment.columnView.items}{materialsStored}

{/payment.columnView.items}

 Returns the line item materials stored value of the payment application. Number
{#payment.columnView.items.completed}

For example:
{#payment.columnView.items}{completed}

{/payment.columnView.items}

 Returns the line item total completed value of the payment application including work completed value and material on site value. Number
{#payment.columnView.items.percentCompleted}

For example:
{#payment.columnView.items}{percentCompleted}

{/payment.columnView.items}

 Returns the line item total completed percentage of the payment application. Number
{#payment.columnView.items.balanceToFinish}

For example:
{#payment.columnView.items}{balanceToFinish}

{/payment.columnView.items}

 Returns the line item balance to finish value of the payment application. Number
{#payment.columnView.items.retainage}

For example:
{#payment.columnView.items}{retainage}

{/payment.columnView.items}

 Returns the line item retention value of the payment application. Number
{#payment.columnView.items.completedWorkRetentionPercent}

For example:
{#payment.columnView.items}{completedWorkRetentionPercent}

{/payment.columnView.items}

 Returns the line item retention percentage of work completed of the payment application. Number
{#payment.columnView.items.materialsOnStoreRetentionPercent}

For example:
{#payment.columnView.items}{materialsOnStoreRetentionPercent}

{/payment.columnView.items}

 Returns the line item retention percentage of materials stored of the payment application. Number
{#payment.columnView.items.completedWorkReleased}

For example:
{#payment.columnView.items}{completedWorkReleased}

{/payment.columnView.items}

 Returns the line item of released retention value of work completed of the payment application. Number
{#payment.columnView.items.materialsOnStoreReleased}

For example:
{#payment.columnView.items}{materialsOnStoreReleased}

{/payment.columnView.items}

 Returns the line item of released retention value of materials stored of the payment application. Number
{payment.columnView.totalOriginalAmount} Returns the total original schedule of value of the payment application, including contract amount, budget transfers, and change orders. Number
{approvedBudgetTransfers} Approved Budget Transfers: The total number of approved budget transfers. Number
{previousApprovedBudgetTransfers} Previous Approved Budget Transfers: The amount of all approved budget transfers in the previous periods. Number
{approvedThisPeriodBudgetTransfers} Approved This Period Budget Transfers: The amount of approved budget transfers added in this period. Number
{totalBudgetTransfers} Total Budget Transfers: The total number of budget transfers. Number
{budgetTransfers} Budget Transfers: The number of budget transfers. Number
{budgetTransfersQuantity} Budget Transfer Quantity: The quantity of budget transfers. Number
{budgetTransfersUnit} Budget Transfer Unit: The unit of measure of the budget transfers. String
{budgetTransfersUnitPrice} Budget Transfer Unit Price: The unit price of budget transfers. Number
{payment.columnView.totalChangeOrders} Returns the total approved change orders' value of the payment application. Number
{payment.columnView.totalRevisedValue} Returns the total revised value of the payment application. Number
{payment.columnView.totalPreviousAmount} Returns the total work completed value of the previous payment application. Number
{payment.columnView.totalAmount} Returns the total work completed value of the current payment application. Number
{payment.columnView.totalMaterialsStored} Returns the total material on site value of the payment application. Number
{previousMaterialsOnStore} Returns the amount for materials stored from all previous applications. Number
{previousClaimedAmount} Returns the claimed amount from previous applications. Number
{claimedAmount} Returns this period work completed claimed amount. Number
{claimedWorkCompleted} Returns total work completed claimed amount. Number
{payment.columnView.totalCompleted} Returns the total completed value of the payment application including materials stored value. Number
{payment.columnView.percentTotalCompleted} Returns the total completed percentage of the payment application including materials stored value. Number
{payment.columnView.totalBalanceToFinish} Returns the total balance to finish value of the payment application. Number
{payment.columnView.totalRetainage} Returns the total retention value of the payment application. Number
{payment.thisPeriodRetainage} Returns the current payment's total retainage minus the previous payment's retainage. Number
{#committedSubItems}{value}{/committedSubItems} Returns the committed amount of cost item’s subitems. Number
{#committedSubItems}{unitPrice}{/committedSubItems} Returns the committed unit price of cost item’s subitems. Number
{latestComment.content} Returns latest review comment for each line. Number
{this.costItem.corNumber} Returns change order information that is linked to cost items. Instead of corNumber, you can also write ocoNumber, scoNumber, scoType, corType, ocoType, corName, ocoName, or scoName to include needed information. Number
{materialsBilled}
For example:
{payment.columnView.materialsBilled}		 If the Materials Billed setting is enabled, the variable returns the materials billed amount. Learn more about Materials in Payment Applications. Number
{previousMaterialsBilled}
For example:
{payment.columnView.previousMaterialsBilled}		 If the Materials Billed setting is enabled, the variable returns the materials billed amount from the previous application. Learn more about Materials in Payment Applications. Number
{payment.lineView.materials}
For example:
{payment.lineView.materials}		 If the Materials Billed setting is enabled, this variable returns the total materials billed for each line item, calculated as previousMaterialsBilled + materialsBilled (this period). This provides a single variable to get the cumulative materials billed amount. Learn more about Materials in Payment Applications. Number
{previousAmount | add: previousMaterialsBilled} If the Materials Billed setting is enabled, the variable returns the sum of previous work completed and materials billed. Learn more about Materials in Payment Applications. Number
{payment.columnView.totalPreviousAmount | add:payment.columnView.previousMaterialsBilled} If the Materials Billed setting is enabled, the variable provides the combined total of previous work completed and materials billed. Learn more about Materials in Payment Applications. Number
{totalAdvanceAmount} The total advance amount of all periods. Number
{totalAdvancePercent} The advance percent of all periods. Number
{totalRecoupmentAmount} The total recoupment amount of all periods. Number
{totalRecoupmentPercentOfAdvance} The recoupment percent of this period. Number
{advanceAmount} The advance amount of this period. Number
{advancePercent} The advance percent of this period. Number
{recoupmentAmount} The recoupment amount of this period. Number
{recoupmentPercentOfCompletedWork} The recoupment percent of completed work. Number
{previousAdvanceAmount} The percentage of recoupment for the work completed in this period. Number
{previousRecoupmentAmount} The amount of the previous recoupment. Number
{previousAdvanceAmountForeignCurrency} {previousAdvanceAmount} value in the foreign currency. Number
{previousRecoupmentAmountForeignCurrency} {previousRecoupmentAmount} value in the foreign currency. Number
{payment.columnView.totalOriginalAmount} Returns the total original schedule of value of the payment application, including contract amount, budget transfers, and change orders. Number
{approvedBudgetTransfers} Returns the total number of approved budget transfers. Number
{previousApprovedBudgetTransfers} Returns the amount of all approved budget transfers in the previous periods. Number
{approvedThisPeriodBudgetTransfers} Returns the amount of approved budget transfers added in this period. Number
{totalBudgetTransfers} Returns the total number of budget transfers. Number
{budgetTransfers} Returns the number of budget transfers. Number
{budgetTransfersQuantity} Returns the quantity of budget transfers. Number
{budgetTransfersUnit} Returns the unit of measure of the budget transfers. String
{budgetTransfersUnitPrice} Returns the unit price of budget transfers. Number
Parent page: Variables in Cost Management