Release Retainage

In some industries, such as construction, it is necessary to withhold a portion of the contract amount until the work has been completed to ensure that the vendor will satisfy its obligations and complete a particular project. If you are using the REST API to integrate MYOB Acumatica with an external system, this external system can process bills and debit adjustments with retained amounts, including the creation of retainage documents (that is, the release of retainage) on the Bills and Adjustments (AP301000) form. For details about releasing retainage, see Processing AP Documents with Retainage.

Testing of the Request

Before you test the code below, you need to configure your client application and the MYOB Acumatica instance to be used as follows:
  1. Deploy a new MYOB Acumatica instance with the U100 dataset. For details on deploying an instance, see To Deploy an MYOB Acumatica Instance.
  2. On the Enable/Disable Features (CS100000) form, make sure that the Retainage Support feature is enabled.
  3. To sign in to the instance in the client application, use the tenant name (which you specified when you created the instance) and the HEADOFFICE branch.
  4. If you use Postman as the client application for testing, in the IntegrationDevelopmentGuide.postman_collection.json collection (which is located in the IntegrationDevelopment\Help folder of the Help-and-Training-Examples repository on GitHub), make sure the collection variables have the proper values.

Request

You can use the following request example to create a retainage bill in the amount of $500 through the REST API. In the example, you specify April 1, 2024 as the business date. As a result of this request, a new bill is created on the Bills and Adjustments (AP301000) form with the Retainage Document check box selected.
Tip: In the request example below, <MYOB Acumatica instance URL> is the URL of the MYOB Acumatica instance (such as https://my.acumatica.com/MyInstance). You can omit the instance name in the URL (that is, you can use https://my.acumatica.com) if the instance is installed in the root of the website.
POST /Bill/ReleaseRetainage HTTP/1.1
Host: [<MYOB Acumatica instance URL>]/entity/Default/23.200.001
Accept: application/json
Content-Type: application/json
PX-CbApiBusinessDate: 2024/04/01

{
    "entity": {
        "Type": {
            "value": "Bill"
        },
        "ReferenceNbr": {
            "value": "000072"
        }
    },
    "parameters": {
        "Date": {
            "value": "2024-03-01T11:00:00.000Z"
        },
        "PostPeriod": {
            "value": "032024"
        },
        "AmtToRelease": {
            "value": 500
        }
    }
}

Usage Notes

In the body of the request, you can identify the entity by using the entity ID or the key fields, which are the following:
  • Type: The type of the document, which can be one of the following: Bill, Debit Adj.
  • ReferenceNbr: The number that identifies the AP document in the system
In the body of the request, you specify the following parameters of the ReleaseRetainage action:
  • Date: Required. The date of the created AP retainage document.
  • PostPeriod: Required. The post period of the created AP retainage document.
  • AmtToRelease: Optional. The retained amount to be released. If AmtToRelease is not specified, the AP retainage document is created in the amount of 100% of the unreleased retainage from each line in the original document. An error is returned as a result of the action execution in any of the following cases:
    • If the unreleased retainage amount of the document is less than the specified AmtToRelease value
    • If AmtToRelease is greater than 0 and the AP document for which the action is executed has the Pay by Line check box selected on the Bills and Adjustments (AP301000) form
    • If AmtToRelease is less than or equal to 0