Working with Requisitions

Introduction

Commitments invoices, or requisitions, allow subcontractors to progressively bill at several stages during the construction process. These billings are based on a verified percentage of that commitment's completion. General contractors can configure billing period start and end dates, as well as the billing date, for each billing period. They can invite subcontractors to complete requisitions for the most recent billing period, or they can create requisitions on behalf of the subcontractor. Once the requisition has been approved, payment can be issued against the commitment.

For addtional detail on requisitions and how they work in Procore, see Information on Requisitions on our Support Site.

Requisitions API Endpoints

The Procore API provides a number of endpoints that allow you perform actions on requisitions in Procore. The following table provides descriptions of these endpoints. Clicking an endpoint title in the table takes you to the reference page for that endpoint where you can learn about the various parameters and response body attributes.

Requisition Endpoint Description
Create Requisition For Commitment Creates a new requisition for the specified commitment.
List Requisitions For Project Lists existing requisitions for the specified project.
Show Requisition Shows information for the specified requisition.
Show Detail for Requisition Shows detailed information for the specified requisition.
Update Requisition Updates attributes for the specified requisition. Must be the latest, open requisition. Closed requisitions cannot be updated.
Delete Requisition Deletes the specified requisition. Must be the latest, open requisition. Closed requisitions cannot be deleted.
List Requisition Contract Items Lists the contract items associated with the specified requisition.
Show Requisition Contract Item Shows information on the specified contract item.
Update Requisition Contract Item Updates attributes for the specified contract item.
Add a Change Order Package to a Requisition Creates an association, or link, between the specified requisition and an existing change order package. The change order package must be in the 'approved' state.
List Requisition Change Order Items Lists the change order items associated with the specified requisition.
Show Requisition Change Order Item Shows information for a change order item in the specified requisition.
Update Requisition Change Order Item Updates attributes for the specified change order item.

Common Requisitions Workflows

Here are the common workflows you will employ when working with the requisitions API endpoints.

Requisitions Against a Commitment

The desired outcome of this workflow is a new requisition created against an existing commitment, along with updated commitment line items for the current billing period.

  1. First, we create a new requisition against an existing commitment using the Create Requisition for Commitment endpoint. You will need to supply a JSON request body that includes the project_id and commitment_id, as well as the requisition object containing a minimum number of required attributes. Here is an example JSON request body.

    { "project_id": 123456, "commitment_id": 786001, "requisition": { "period_id": 117330, "requisition_start": "2016-11-01", "requisition_end": "2016-11-30", "billing_date": "2017-11-01", "invoice_number": 123, "status": "draft" } }

    Here is the JSON response:

    { "id": 1280646, "billing_date": "2017-11-01", "commitment_id": 786001, "invoice_number": "123", "origin_data": null, "origin_id": null, "percent_complete": "96.36%", "period_id": 117330, "status": "draft", "requisition_start": "2016-11-01", "requisition_end": "2016-11-30", "number": 19, "g702": { "balance_to_finish_including_retainage": "7300.00", "completed_work_retainage_percent": "10.00", "completed_work_retainage_amount": "5200.00", "contract_sum_to_date": "55000.00", "current_payment_due": "0.00", "less_previous_certificates_for_payment": "47700.00", "net_change_by_change_orders": "5000.00", "original_contract_sum": "50000.00", "stored_materials_retainage_amount": "100.00", "stored_materials_retainage_percent": "10.00", "total_completed_and_stored_to_date": "53000.00", "total_earned_less_retainage": "47700.00", "total_retainage": "5300.00" }, "attachments": [] }
    Make note of the id attribute returned in the response body, as you will need to include that in the next step.

  2. Next, we retrieve a list of contract items by making a call to the List Requisition Contract Items endpoint. We use the value of the id attribute returned from the previous step as the required requisition_id path parameter and the project_id as the required query parameter. This helps us verify that we have created the requisition correctly and that it contains at least one associated contract line item.

    { "id": 17918097, "cost_code_id": 80598390, "line_item_id": 5175960, "description_of_work": "Foundation work", "scheduled_value": "50000.00", "work_completed_from_previous_application": "51000.00", "work_completed_this_period": "0.00", "materials_presently_stored": "500.00", "total_completed_and_stored_to_date": "51500.00", "total_completed_and_stored_to_date_percent": "103.00", "work_completed_retainage_from_previous_application": "5100.00", "work_completed_retainage_retained_this_period": "0.00", "work_completed_retainage_percent_this_period": "10.00", "materials_stored_retainage_currently_retained": "50.00", "materials_stored_retainage_percent_this_period": "10.00", "work_completed_retainage_released_this_period": "0.00", "materials_stored_retainage_released_this_period": "0.00" }
  3. Finally, we make one or more calls to the Update Requisition Contract Item endpoint to update line item attributes as needed for the current billing period. For this call we include the requisition_id as a required path parameter and the project_id as a required query parameter. We send a payload to the Contract Item object containing a minimum number of required attributes. Here is an example JSON request body for updating the description for a Contract Item along with work completed figures.

    { "requisition_contract_item": { "work_completed_this_period": "1000", "work_completed_this_period_quantity": "0.20", "Description": "Initial prep work" } }

Requisitions with Change Orders

In some projects you may need to manipulate requisition data in the context of change orders. The outcome of the following workflow is a change order package including one or more change order line items associated with a requisition.

  1. First we make a call to the Add a Change Order Package to a Requisition endpoint to associate an existing change order package with a requisition. We pass the requisition_id as a required path parameter, and the commitment_id, project_id, and change_order_package_id as required query parameters. The response to this call shows the change order items from the specified change order package automatically added to the requisition.

    [ { "id": 592007, "cost_code_id": 80598417, "line_item_id": 11786340, "description_of_work": "Landscape design re-work", "scheduled_value": "500.00", "work_completed_from_previous_application": "0.00", "work_completed_this_period": "100.00", "total_completed_and_stored_to_date": "100.00", "total_completed_and_stored_to_date_percent": "20.00", "work_completed_retainage_from_previous_application": "0.00", "work_completed_retainage_retained_this_period": "0.00", "work_completed_retainage_percent_this_period": "0.00", "work_completed_retainage_released_this_period": "0.00", "scheduled_quantity": "0.0", "scheduled_unit_price": "0.0000", "work_completed_this_period_quantity": "0.0", "work_completed_from_previous_application_quantity": "0.0", "change_order_package_id": 1708957 }, { "id": 592006, "cost_code_id": 80598417, "line_item_id": 11786339, "description_of_work": "Civil design for extended driveway", "scheduled_value": "2000.00", "work_completed_from_previous_application": "0.00", "work_completed_this_period": "500.00", "total_completed_and_stored_to_date": "500.00", "total_completed_and_stored_to_date_percent": "25.00", "work_completed_retainage_from_previous_application": "0.00", "work_completed_retainage_retained_this_period": "0.00", "work_completed_retainage_percent_this_period": "0.00", "work_completed_retainage_released_this_period": "0.00", "scheduled_quantity": "0.0", "scheduled_unit_price": "0.0000", "work_completed_this_period_quantity": "0.0", "work_completed_from_previous_application_quantity": "0.0", "change_order_package_id": 1708957 } ]
  2. With the change order package successfully added to the requisition, we can now make a call to the List Requisition Change Order Items endpoint to verify that each of the change orders contained in the package are appropriately associated with the requisition as line items. We pass the requisition_id as a required path parameter and the project_id as a required query parameter. The result of this call should be the same as what we see in the previous step.

  3. We can now make a call to the Update Requisition Change Order Item endpoint to update the line item values for the current requisition billing period. For this endpoint we pass the requisition_id and the id for the change order item we want to update as required path parameters. In the JSON request body we specify the modifications we want to make to the line item as illustrated in the following example.

    { "requisition_change_order_item":{ "work_completed_this_period":"1000.00", "work_completed_this_period_quantity":"10" } }

    Here is the JSON response:

    { "id": 592006, "cost_code_id": 80598417, "line_item_id": 11786339, "description_of_work": "Civil design for extended driveway", "scheduled_value": "1500.00", "work_completed_from_previous_application": "0.00", "work_completed_this_period": "1000.00", "total_completed_and_stored_to_date": "1000.00", "total_completed_and_stored_to_date_percent": "66.67", "work_completed_retainage_from_previous_application": "0.00", "work_completed_retainage_retained_this_period": "0.00", "work_completed_retainage_percent_this_period": "0.00", "work_completed_retainage_released_this_period": "0.00", "scheduled_quantity": "15.0", "scheduled_unit_price": "100.0000", "work_completed_this_period_quantity": "10.0", "work_completed_from_previous_application_quantity": "0.0", "change_order_package_id": 1708957 }

Additional Information

We recommend the following articles on our Support Site to help you build your understanding of Requisitions, how they are managed in Procore, and their relationship to commitments and change orders.