WIP periods

Use WIP schedule periods to monitor profitability and revenue recognition for ongoing projects. The WIP schedule periods are based on the reporting periods in your entity. See Work in progress (WIP) management for details.

List WIP periods

get/objects/construction-forecasting/wip-period

Returns a collection with a key, ID, and link for each WIP period. This operation is mostly for use in testing; use query to find objects that meet certain criteria and to specify properties that are returned.

Permissions and other requirements
SubscriptionConstruction
User typeBusiness, Project Manager
PermissionsList, View WIP Periods
SecurityOAuth2
Responses
200

OK

400

Bad Request

Request samples
Response samples
application/json
{
  • "ia::result": [
    • {
      • "id": "8",
      • "key": "8",
      • "href": "/objects/construction-forecasting/wip-period/8"
      },
    • {
      • "id": "9",
      • "key": "9",
      • "href": "/objects/construction-forecasting/wip-period/9"
      }
    ],
  • "ia::meta": {
    • "totalCount": 2,
    • "totalSuccess": 2,
    • "totalError": 0
    }
}

Create a WIP period

post/objects/construction-forecasting/wip-period

Creates a new WIP period.

Permissions and other requirements
SubscriptionConstruction
User typeBusiness, Project Manager
PermissionsAdd WIP Periods
SecurityOAuth2
Request
Request Body schema: application/json
required

Create a new WIP period.

periodName
required
string

The name for the reporting period on which the WIP schedule is based.

Example: "Month end May 2023"
periodEndDate
required
string <date>

The ending date of the WIP schedule's reporting period.

Example: "2023-05-31"
required
object

The entity location assigned to this WIP period.

key
string

System-assigned key for the location.

Example: "1"
id
string

Unique identifier for the location.

Example: "USAE"
periodStartDate
string <date>

The beginning date of the WIP schedule's reporting period.

Example: "2023-05-01"
state
string
Default: "unposted"

The state is posted if the WIP projects are finalized and posted to the general ledger, otherwise, it is unposted.

A period is ready to be posted when:

  • The state of the WIP period is set to unposted
  • The WIP period is not a manually imported historical period (isHistoricalImport is set to false)
  • The prior WIP period does not exist, or the prior period’s state is set to posted
  • The WIP projects are marked as finalized (wip-project.isFinalized is set to true)
  • All books are open for posting
Enum: "posted" "unposted"
Example: "unposted"
notes
string

Notes or comments about the WIP period.

Example: "Review with the team"
isHistoricalImport
boolean
Default: false

Indicates whether this is a manually imported historical WIP period.

Example: false
lastRefreshDateTime
string <date-time>

The date and time the WIP period was last updated with the latest project data and any changes to the projects included in the WIP schedule.

Example: "2023-05-26T10:06:00Z"
object

The entity from which this WIP period was created.

key
string

System-assigned key for the entity.

Example: "1"
id
string

Unique identifier for the entity.

Example: "USAE"
object

The WIP period at the end of the prior fiscal year, if one exists.

key
string

Key for the WIP period.

Example: "123"
Array of objects

WIP projects the WIP schedule period is based on.

Array
key
string

System-assigned key for the WIP project.

Example: "1"
isFinalized
boolean
Default: false

A WIP project is finalized when it is ready to be posted to the general ledger.

Enum: false true
Example: false
estimatedCostToDateAmount
string <decimal-precision-2>

The project's estimated costs to-date based on estimate entries in the project's primary estimate. Estimate entries are included if they meet the following criteria:

  • Have a workflow type of original, revision, or approved change.
  • Have an effective date that falls before or on the end date for the WIP schedule.
Example: "10000.00"
jobToDateCosts
string <decimal-precision-2>

The project's actual costs to-date. This amount comes from journal postings to the selected cost accounts.

Example: "1000.00"
estimatedCostToComplete
string <decimal-precision-2>

Estimate of the costs remaining for the project. The amount is calculated as estimatedCostAtCompletion less jobToDateCosts.

Example: "3000.00"
estimatedCostAtCompletion
string <decimal-precision-2>

Estimated cost at completion of the project based on estimate entries in the project's primary estimate. Estimate entries are included if they have a workflow type of original, revision, or approved change.

Example: "3000.00"
pendingEstimatesAmount
string <decimal-precision-2>

Estimated pending amount based on pending estimate entries in the project's primary estimate.

Example: "3000.00"
estimatedPercentComplete
string <percent-precision-2>

Estimated percent complete for the project, calculated as project's jobToDateCosts divided by estimatedCostAtCompletion.

Example: 70.5
object

Project manager's forecast of project costs, profits, and completion percentage.

object

CFO forecast of project costs, profits, and completion percentage.

costAtCompletionVariance
string <decimal-precision-2>

Cost at completion variance (cfoForecast.costAtCompletion less estimatedCostAtCompletion).

Example: "500.00"
totalContractValue
string <decimal-precision-2>

The sum of the price for all project contract lines, including any change request entries linked to the project contract line through a change order.

A project contract line entry is included in the calculation if it meets the following conditions:

  • The workflow type is original or revision, or approved change (change request entry).
  • The price effective date is earlier than or on the end date of the WIP schedule period.
Example: "10000.00"
contractVarianceAmount
string <decimal-precision-2>

Contract amount variance (cfoForecast.contractValue less totalContractValue).

Example: "1000.00"
jobToDateBillings
string <decimal-precision-2>

Job-to-date billings amount comes from journal postings to the revenue accounts specified in the WIP setup object.

Journal entries are included in this amount if they meet the following conditions:

  • The account is specified as a revenue account in the list of accounts in the WIP setup object.

  • The project dimension assigned to the journal entry matches the WIP project or one of its child projects.

  • The entry date for the journal entry falls before the WIP schedule period end date.

A credit amount posted to the account is added to the job-to-date billed amount. A debit is subtracted.

Example: "5000.00"
earnedToDateAmount
string <decimal-precision-2>

Earned-to-date amount (cfoForecast.contractValue multiplied by cfoForecast.percentComplete).

This amount reflects the earnings from the beginning of the project; it is not limited to the current year.

Example: "5000.00"
remainingBacklogAmount
string <decimal-precision-2>

Remaining backlog amount represents the work left for the project as a currency amount (cfoForecast.contractValue less earnedToDateAmount).

Example: "3000.00"
overUnderBillingAmount
string <decimal-precision-2>

The overbilling or underbilling amount is the difference between YTD billed and YTD earned amounts.

Example: "-1000.00"
earnedProfitToDateAmount
string <decimal-precision-2>

Current earned profit to-date (earnedToDateAmount less jobToDateCosts).

Example: "5000.00"
grossProfitPercentOfContract
string <percent-precision-2>

Gross profit percent of contract (cfoForecast.grossProfitAtCompletion divided by cfoForecast.contractValue).

Example: 20
grossProfitPercentOfCost
string <percent-precision-2>

Gross profit percent of cost (cfoForecast.grossProfitAtCompletion divided by cfoForecast.costsAtCompletion).

Example: 30
totalGrossProfitEstimatedAtCompletion
string <decimal-precision-2>

Total gross profit estimated at completion (totalContractValue less estimatedCostAtCompletion).

Example: "3000.00"
cfoForecastGrossProfitAtCompletion
string <decimal-precision-2>

CFO forecast gross profit at completion (cfoForecast.contractValue less cfoForecast.costsAtCompletion).

Example: "3000.00"
grossProfitVarianceAmount
string <decimal-precision-2>

Gross profit variance (cfoForecast.grossProfitAtCompletion less totalGrossProfitEstimatedAtCompletion).

Example: "1000.00"
cfoForecastGrossProfitMarginPercent
string <percent-precision-2>

CFO forecast gross profit margin percent (cfoForecast.grossProfitAtCompletion divided by cfoForecast.contractValue).

Example: 30
priorYearsProfit
string <decimal-precision-2>

Earned to-date profit (earnedToDateAmount less jobToDateCost).

Example: "20000.00"
endOfPriorYearEarnedToDateAmount
string <decimal-precision-2>

Earned to-date amount as of end of prior year (earnedToDateAmount less endOfPriorYearEarnedProfit).

Example: "15000.00"
endOfPriorYearEarnedProfit
string <decimal-precision-2>

Earned profit as of end of prior year. This value comes from the end-of-year WIP schedule from the prior year if one exists. Otherwise, the amount is zero.

Example: "15000.00"
remainingProfit
string <decimal-precision-2>

The amount of the project that remains to be earned (cfoForecast.grossProfitAtCompletion less earnedProfitToDate).

Example: "15000.00"
yearToDateCostAmount
string <decimal-precision-2>

Year-to-date costs.

Example: "15000.00"
yearToDateBillingAmount
string <decimal-precision-2>

Year-to-date billings.

Example: "15000.00"
yearToDateEarnedRevenueAmount
string <decimal-precision-2>

Year-to-date earned revenue.

Example: "15000.00"
jobToDateOverBillingAmount
string <decimal-precision-2>

Job-to-date over billing.

Example: "15000.00"
jobToDateUnderBillingAmount
string <decimal-precision-2>

Job-to-date under billing.

Example: "15000.00"
yearToDateEarnedProfitAmount
string <decimal-precision-2>

Year-to-date earned profit.

Example: "15000.00"
currentPeriodBillingAmount
string <decimal-precision-2>

Current period billings.

Example: "15000.00"
currentPeriodCostAmount
string <decimal-precision-2>

Current period costs.

Example: "15000.00"
currentPeriodEarnedProfitAmount
string <decimal-precision-2>

Current period earned profit.

Example: "15000.00"
currentPeriodEarnedRevenueAmount
string <decimal-precision-2>

Current period earned revenue.

Example: "15000.00"
notes
string

Notes or comments about the WIP project.

Example: "no comments"
Array of objects

WIP forecast details for the WIP project

object

The project this WIP project is based on.

object

The customer associated with the project.

object

The WIP period this WIP project is associated with.

Responses
201

Created

400

Bad Request

Request samples
application/json
{
  • "periodName": "Month Ended May 2023",
  • "periodEndDate": "2023-05-31",
  • "notes": "demo",
  • "state": "unposted",
  • "lastRefreshDateTime": "2023-06-02T20:29:13Z",
  • "assignedEntity": {
    • "key": "65"
    },
  • "wipProjects": [
    • {
      • "cfoForecastGrossProfitMarginPercent": 0.99,
      • "cfoForecast": {
        },
      • "cfoForecastGrossProfitAtCompletion": "26110.00",
      • "estimatedCostToComplete": "-5203.07",
      • "overUnderBillingAmount": "76578540.49",
      • "isFinalized": false,
      • "projectManagerForecast": {
        },
      • "priorYearsProfit": "0",
      • "remainingProfit": "0",
      • "endOfPriorYearEarnedToDateAmount": "0",
      • "endOfPriorYearEarnedProfit": "0",
      • "remainingBacklogAmount": "-76557103.65",
      • "contractVarianceAmount": "0",
      • "estimatedPercentComplete": 29.12,
      • "totalGrossProfitEstimatedAtCompletion": "26110.00",
      • "grossProfitVarianceAmount": "0.00",
      • "jobToDateBillings": "4858.16",
      • "jobToDateCosts": "5388.07",
      • "estimatedCostToDateAmount": "185.00",
      • "earnedProfitToDateAmount": "76578010.58",
      • "earnedToDateAmount": "76583398.65",
      • "grossProfitPercentOfContract": 0.99,
      • "grossProfitPercentOfCost": 141.14,
      • "totalRevisedContract": "26295.00",
      • "yearToDateCostAmount": "15000",
      • "yearToDateBillingAmount": "15000",
      • "yearToDateEarnedRevenueAmount": "15000",
      • "jobToDateOverBillingAmount": "15000",
      • "jobToDateUnderBillingAmount": "15000",
      • "yearToDateEarnedProfitAmount": "15000",
      • "currentPeriodBillingAmount": "15000",
      • "currentPeriodCostAmount": "15000",
      • "currentPeriodEarnedProfitAmount": "15000",
      • "currentPeriodEarnedRevenueAmount": "15000",
      • "project": {
        }
      }
    ]
}
Response samples
application/json
{
  • "ia::result": {
    • "key": "41",
    • "id": "41",
    • "href": "/objects/construction-forecasting/wip-period/41"
    },
  • "ia::meta": {
    • "totalCount": 1,
    • "totalSuccess": 1,
    • "totalError": 0
    }
}

Get a WIP period

get/objects/construction-forecasting/wip-period/{key}

Returns detailed information for a specified WIP period.

Permissions and other requirements
SubscriptionConstruction
User typeBusiness, Project Manager
PermissionsList, View WIP Periods
SecurityOAuth2
Request
path Parameters
key
required
string

System-assigned key for the WIP period.

Example: 155
Responses
200

OK

400

Bad Request

Request samples
Response samples
application/json
{
  • "ia::result": {
    • "audit": {
      • "createdBy": 1,
      • "createdDateTime": "2023-06-02T20:29:28Z",
      • "modifiedBy": 1,
      • "modifiedDateTime": "2023-06-02T20:29:28Z"
      },
    • "isHistoricalImport": false,
    • "notes": "demo",
    • "lastRefreshDateTime": "2023-06-02T20:29:13Z",
    • "periodName": "Month Ended May 2023",
    • "id": "41",
    • "state": "unposted",
    • "key": "41",
    • "periodEndDate": "2023-05-31",
    • "assignedEntity": {
      • "id": 1,
      • "key": "US",
      • "name": "United States of America",
      • "href": "/objects/company-config/location/1"
      }
    },
  • "ia::meta": {
    • "totalCount": 1,
    • "totalSuccess": 1,
    • "totalError": 0
    }
}

Update a WIP period

patch/objects/construction-forecasting/wip-period/{key}

Updates an existing WIP period by setting the field values. Any fields not provided remain unchanged.

Permissions and other requirements
SubscriptionConstruction
User typeBusiness, Project Manager
PermissionsEdit WIP Periods
SecurityOAuth2
Request
path Parameters
key
required
string

System-assigned key for the WIP period.

Example: 155
Request Body schema: application/json
periodName
string

The name for the reporting period on which the WIP schedule is based.

Example: "Month end May 2023"
periodStartDate
string <date>

The beginning date of the WIP schedule's reporting period.

Example: "2023-05-01"
periodEndDate
string <date>

The ending date of the WIP schedule's reporting period.

Example: "2023-05-31"
state
string
Default: "unposted"

The state is posted if the WIP projects are finalized and posted to the general ledger, otherwise, it is unposted.

A period is ready to be posted when:

  • The state of the WIP period is set to unposted
  • The WIP period is not a manually imported historical period (isHistoricalImport is set to false)
  • The prior WIP period does not exist, or the prior period’s state is set to posted
  • The WIP projects are marked as finalized (wip-project.isFinalized is set to true)
  • All books are open for posting
Enum: "posted" "unposted"
Example: "unposted"
notes
string

Notes or comments about the WIP period.

Example: "Review with the team"
isHistoricalImport
boolean
Default: false

Indicates whether this is a manually imported historical WIP period.

Example: false
lastRefreshDateTime
string <date-time>

The date and time the WIP period was last updated with the latest project data and any changes to the projects included in the WIP schedule.

Example: "2023-05-26T10:06:00Z"
object

The entity from which this WIP period was created.

key
string

System-assigned key for the entity.

Example: "1"
id
string

Unique identifier for the entity.

Example: "USAE"
object

The entity location assigned to this WIP period.

key
string

System-assigned key for the location.

Example: "1"
id
string

Unique identifier for the location.

Example: "USAE"
object

The WIP period at the end of the prior fiscal year, if one exists.

key
string

Key for the WIP period.

Example: "123"
Array of objects

WIP projects the WIP schedule period is based on.

Array
key
string

System-assigned key for the WIP project.

Example: "1"
isFinalized
boolean
Default: false

A WIP project is finalized when it is ready to be posted to the general ledger.

Enum: false true
Example: false
estimatedCostToDateAmount
string <decimal-precision-2>

The project's estimated costs to-date based on estimate entries in the project's primary estimate. Estimate entries are included if they meet the following criteria:

  • Have a workflow type of original, revision, or approved change.
  • Have an effective date that falls before or on the end date for the WIP schedule.
Example: "10000.00"
jobToDateCosts
string <decimal-precision-2>

The project's actual costs to-date. This amount comes from journal postings to the selected cost accounts.

Example: "1000.00"
estimatedCostToComplete
string <decimal-precision-2>

Estimate of the costs remaining for the project. The amount is calculated as estimatedCostAtCompletion less jobToDateCosts.

Example: "3000.00"
estimatedCostAtCompletion
string <decimal-precision-2>

Estimated cost at completion of the project based on estimate entries in the project's primary estimate. Estimate entries are included if they have a workflow type of original, revision, or approved change.

Example: "3000.00"
pendingEstimatesAmount
string <decimal-precision-2>

Estimated pending amount based on pending estimate entries in the project's primary estimate.

Example: "3000.00"
estimatedPercentComplete
string <percent-precision-2>

Estimated percent complete for the project, calculated as project's jobToDateCosts divided by estimatedCostAtCompletion.

Example: 70.5
object

Project manager's forecast of project costs, profits, and completion percentage.

object

CFO forecast of project costs, profits, and completion percentage.

costAtCompletionVariance
string <decimal-precision-2>

Cost at completion variance (cfoForecast.costAtCompletion less estimatedCostAtCompletion).

Example: "500.00"
totalContractValue
string <decimal-precision-2>

The sum of the price for all project contract lines, including any change request entries linked to the project contract line through a change order.

A project contract line entry is included in the calculation if it meets the following conditions:

  • The workflow type is original or revision, or approved change (change request entry).
  • The price effective date is earlier than or on the end date of the WIP schedule period.
Example: "10000.00"
contractVarianceAmount
string <decimal-precision-2>

Contract amount variance (cfoForecast.contractValue less totalContractValue).

Example: "1000.00"
jobToDateBillings
string <decimal-precision-2>

Job-to-date billings amount comes from journal postings to the revenue accounts specified in the WIP setup object.

Journal entries are included in this amount if they meet the following conditions:

  • The account is specified as a revenue account in the list of accounts in the WIP setup object.

  • The project dimension assigned to the journal entry matches the WIP project or one of its child projects.

  • The entry date for the journal entry falls before the WIP schedule period end date.

A credit amount posted to the account is added to the job-to-date billed amount. A debit is subtracted.

Example: "5000.00"
earnedToDateAmount
string <decimal-precision-2>

Earned-to-date amount (cfoForecast.contractValue multiplied by cfoForecast.percentComplete).

This amount reflects the earnings from the beginning of the project; it is not limited to the current year.

Example: "5000.00"
remainingBacklogAmount
string <decimal-precision-2>

Remaining backlog amount represents the work left for the project as a currency amount (cfoForecast.contractValue less earnedToDateAmount).

Example: "3000.00"
overUnderBillingAmount
string <decimal-precision-2>

The overbilling or underbilling amount is the difference between YTD billed and YTD earned amounts.

Example: "-1000.00"
earnedProfitToDateAmount
string <decimal-precision-2>

Current earned profit to-date (earnedToDateAmount less jobToDateCosts).

Example: "5000.00"
grossProfitPercentOfContract
string <percent-precision-2>

Gross profit percent of contract (cfoForecast.grossProfitAtCompletion divided by cfoForecast.contractValue).

Example: 20
grossProfitPercentOfCost
string <percent-precision-2>

Gross profit percent of cost (cfoForecast.grossProfitAtCompletion divided by cfoForecast.costsAtCompletion).

Example: 30
totalGrossProfitEstimatedAtCompletion
string <decimal-precision-2>

Total gross profit estimated at completion (totalContractValue less estimatedCostAtCompletion).

Example: "3000.00"
cfoForecastGrossProfitAtCompletion
string <decimal-precision-2>

CFO forecast gross profit at completion (cfoForecast.contractValue less cfoForecast.costsAtCompletion).

Example: "3000.00"
grossProfitVarianceAmount
string <decimal-precision-2>

Gross profit variance (cfoForecast.grossProfitAtCompletion less totalGrossProfitEstimatedAtCompletion).

Example: "1000.00"
cfoForecastGrossProfitMarginPercent
string <percent-precision-2>

CFO forecast gross profit margin percent (cfoForecast.grossProfitAtCompletion divided by cfoForecast.contractValue).

Example: 30
priorYearsProfit
string <decimal-precision-2>

Earned to-date profit (earnedToDateAmount less jobToDateCost).

Example: "20000.00"
endOfPriorYearEarnedToDateAmount
string <decimal-precision-2>

Earned to-date amount as of end of prior year (earnedToDateAmount less endOfPriorYearEarnedProfit).

Example: "15000.00"
endOfPriorYearEarnedProfit
string <decimal-precision-2>

Earned profit as of end of prior year. This value comes from the end-of-year WIP schedule from the prior year if one exists. Otherwise, the amount is zero.

Example: "15000.00"
remainingProfit
string <decimal-precision-2>

The amount of the project that remains to be earned (cfoForecast.grossProfitAtCompletion less earnedProfitToDate).

Example: "15000.00"
yearToDateCostAmount
string <decimal-precision-2>

Year-to-date costs.

Example: "15000.00"
yearToDateBillingAmount
string <decimal-precision-2>

Year-to-date billings.

Example: "15000.00"
yearToDateEarnedRevenueAmount
string <decimal-precision-2>

Year-to-date earned revenue.

Example: "15000.00"
jobToDateOverBillingAmount
string <decimal-precision-2>

Job-to-date over billing.

Example: "15000.00"
jobToDateUnderBillingAmount
string <decimal-precision-2>

Job-to-date under billing.

Example: "15000.00"
yearToDateEarnedProfitAmount
string <decimal-precision-2>

Year-to-date earned profit.

Example: "15000.00"
currentPeriodBillingAmount
string <decimal-precision-2>

Current period billings.

Example: "15000.00"
currentPeriodCostAmount
string <decimal-precision-2>

Current period costs.

Example: "15000.00"
currentPeriodEarnedProfitAmount
string <decimal-precision-2>

Current period earned profit.

Example: "15000.00"
currentPeriodEarnedRevenueAmount
string <decimal-precision-2>

Current period earned revenue.

Example: "15000.00"
notes
string

Notes or comments about the WIP project.

Example: "no comments"
Array of objects

WIP forecast details for the WIP project

object

The project this WIP project is based on.

object

The customer associated with the project.

object

The WIP period this WIP project is associated with.

Responses
200

OK

400

Bad Request

Request samples
application/json
{
  • "state": "posted",
  • "notes": "large under billing"
}
Response samples
application/json
{
  • "ia::result": {
    • "key": "41",
    • "id": "41",
    • "href": "/objects/construction-forecasting/wip-period/41"
    },
  • "ia::meta": {
    • "totalCount": 1,
    • "totalSuccess": 1,
    • "totalError": 0
    }
}

Delete a WIP period

delete/objects/construction-forecasting/wip-period/{key}

Deletes a WIP period.

Permissions and other requirements
SubscriptionConstruction
User typeBusiness, Project Manager
PermissionsDelete WIP Periods
SecurityOAuth2
Request
path Parameters
key
required
string

System-assigned key for the WIP period.

Example: 155
Responses
204

No Content

400

Bad Request

Request samples
Response samples
application/json
{
  • "ia::result": {
    • "ia::error": {
      • "code": "invalidRequest",
      • "message": "A POST request requires a payload",
      • "errorId": "REST-1028",
      • "additionalInfo": {
        },
      • "supportId": "Kxi78%7EZuyXBDEGVHD2UmO1phYXDQAAAAo"
      }
    },
  • "ia::meta": {
    • "totalCount": 1,
    • "totalSuccess": 0,
    • "totalError": 1
    }
}

Query WIP periods

post/services/core/query

Use the query service to find WIP periods that meet certain criteria and to specify the properties that are returned.

SecurityOAuth2
Responses
200

OK

400

Bad Request

Request samples
Response samples
application/json
{
  • "ia::result": {
    • "ia::error": {
      • "code": "invalidRequest",
      • "message": "A POST request requires a payload",
      • "errorId": "REST-1028",
      • "additionalInfo": {
        },
      • "supportId": "Kxi78%7EZuyXBDEGVHD2UmO1phYXDQAAAAo"
      }
    },
  • "ia::meta": {
    • "totalCount": 1,
    • "totalSuccess": 0,
    • "totalError": 1
    }
}