v1/containers/{containerId}/payments/{id}
Retrieves a payment in the given project.
Resource Information
Method and URI | GET https://developer.api.autodesk.com/cost/v1/containers/:containerId/payments/:id |
Authentication Context | user context required |
Required OAuth Scopes | data:read |
Data Format | JSON |
Request
Headers
Authorization* string | Must be Bearer <token> , where <token> is obtained via a three-legged OAuth flow. |
region string | The region where the project data resides, to which this request is routed.
This header is optional because the request is automatically routed to a target region based on the project ID or container ID. Using the header, though, can save lookup time on each API call. For information about verifying the region the data resides in, see the Working with BIM 360 Services in Different Regions section on the API Basics page. Possible values: |
Request
URI Parameters
containerId string: UUID | The ID of the cost container for the project. Each project is assigned a container that stores all of the cost data for the project.
To find the container ID, see the Retrieve a Cost Container ID tutorial. In ACC projects, the container ID is the same as the project ID. To obtain a project ID, use GET projects. |
id array: string: uuid | The unique ID of the payment to retrieve. |
Request
Query String Parameters
include array: string | Include nested resources in the response. For example, include=paymentReferences will return payment references to each payment. include=attributes will return custom attributes which represents the “properties” in the response. Possible values: paymentReferences , attributes , summaryCalculatedFields , complianceExpiration . |
Response
HTTP Status Code Summary
200 OK | Success |
400 Bad Request | The parameters are invalid. |
401 Unauthorized | The provided bearer token is invalid. |
403 Forbidden | Forbidden. The user or service represented by the bearer token does not have permission to perform this operation. |
404 Not Found | The resource or endpoint cannot be found. |
409 Conflict | The request could not be completed due to a conflict with the current state of the resource. |
429 Too Many Requests | Rate limit exceeded. Retry your request after a few minutes. |
500 Internal Server Error | An unexpected error occurred on the server. |
503 Service Unavailable | Service unavailable. |
Response
Body Structure (200)
id string: UUID | The unique identifier of the payment. |
billingPeriodId string: UUID | Not relevant |
previousPaymentId string: UUID | The unique identifier of the previous payment for this payment. |
associationId string: UUID | The ID of the contract or main contract that the payment is associated with. |
mainContractId string: UUID | The ID of the main contract associated with this payment. |
budgetPaymentId string,null | The ID of the budget payment associated with this cost payment. This field is valid only for cost payments. |
associationType enum:string | The type of contract associated with this payment.
Possible values: |
startDate string | The start date of this payment. |
endDate string | The end date of this payment. |
dueDate string | The due date of this payment. |
number string | The number of this payment.
Max length: 255 |
name string | The name of this payment.
Max length: 1024 |
description string | A detailed description of this payment. |
note string | The note attached to the payment, if returned. The note consists of Tiptap formatted rich text. For more information, see https://tiptap.dev. |
approvedAt string,null | The date and time that the item was approved, in ISO 8601 format. |
calculatedAt string,null | The date and time that the item was calculated, in ISO 8601 format. |
calculatedBy string | The ID of the user who calculated the payment. |
companyId string,null | The ID of a company managed by a BIM 360 Admin. Detailed company information can be retrieved by calling GET projects/:project_id/companies and locating the member_group_id in the response. |
companyUid string,null | The unique ID (UUID) of the company in this account. Detailed company information can be retrieved using this UUID by calling GET companies/:company_id in the response. |
contactId string,null | The ID of a contact managed by a BIM 360 Admin. |
creatorId string,null | The user who created the payment. This is the ID of a user managed by BIM 360 Admin. |
status enum:string | The status of this payment. For details about the possible values of this field, see Payment Application Statuses.
Possible values: |
paidAt string,null | The date and time when the expense is paid. |
forecastDistributionAt string,null | The date and time determine which distribution period this payment belongs to, after the status of status is set to approved or paid . |
submittedAt string,null | The date and time when the payment is submitted. |
contractAmount number,string,null | The original contract amount of the payment. |
originalAmount number,string,null | The original amount of the payment, including the contract amount and change orders. |
amount number,string,null | The net amount of the payment. |
previousAmount number,string,null | The total of the net amounts previously paid to this point. |
currentCompletedWorkRetentionPercent number | Not relevant |
completedWorkRetainedPercent number | Not relevant |
completedWorkRetention number,string,null | The retention amount of the payment for work completed. |
completedWorkGrossRetentionPercent number | The percentage of the gross retention amount of the payment for work completed. (released value is not removed) |
currentMaterialsRetentionPercent number | Not relevant |
materialsOnStoreRetention number,string,null | The retention amount of the payment for material on site. This parameter is deprecated |
materialsRetention number,string,null | The retention amount of the payment for material. |
materialsGrossRetentionPercent number | The percentage of the gross retention of the payment for material (released value is not removed). |
materialsRetainedPercent number | Not relevant |
totalGrossRetentionPercent number | The percentage of the gross retention of the payment for work completed and material. (released value is not removed) |
totalRetainedPercent number | Not relevant |
previousRetention number,string,null | The total of the amounts previously retained to this point. |
netRetention number,string,null | The net retention amount of this period, which equals to (completedWorkRetention + materialsOnStoreRetention - previousRetention). |
materialsOnStore number,string,null | The amount of the material currently on site. |
previousMaterialsOnStore number,string,null | The amount of the material on site in the previous payment. |
materialsBilled number,string,null | The amount of the material currently billed. |
previousMaterialsBilled number,string,null | The amount of the material billed in last payment. |
netMaterialsOnStore number,string,null | The net change of materials on store of this period, which equals to (materialsOnStore - previousMaterialsOnStore). |
approvedChangeOrders number,string,null | The total amount of approved change orders in this period. |
previousApprovedChangeOrders number,string,null | The total amount of previously approved change orders. |
netAmount number,string,null | The net amount that should be paid in this period, including work completed, material on site, retention and release. |
advanceAmount number,string,null | The advance amount of this period. |
advancePercent number,null | The advance percent of this period. |
previousAdvanceAmount number,string,null | The amount of the previous advance. |
previousAdvanceAmountForeignCurrency number,string,null | previousAdvanceAmount value in the foreign currency. |
recoupmentAmount number,string,null | The recoupment amount of this period. |
recoupmentPercentOfCompletedWork number,null | The percentage of recoupment for the work completed in this period. |
previousRecoupmentAmount number,string,null | The amount of the previous recoupment. |
previousRecoupmentAmountForeignCurrency number,string,null | previousRecoupmentAmount value in the foreign currency. |
aggregateBy string,null | Not relevant |
hasItemRejected boolean | Indicate if this payment has item rejected. This parameter is deprecated. |
hasItemReviewed boolean | Indicate if this payment has item reviewed. This parameter is deprecated. |
exchangeRate number,string,null | Exchange rate. Default value is 1 . If multi-currency is not enabled, it will also be 1 . |
previousExchangeRate number,string,null | Cost Pay Application exchange rate for previous billing period. Default value is 1 , if multi-currency is not enabled, it will also be 1 . |
previousAmountForeignCurrency number,string,null | The foreign currency equivalent of the previous amount. |
previousClaimedAmountForeignCurrency number,string,null | The foreign currency equivalent of the previous claimed amount. |
contractAmountForeignCurrency number,string,null | Foreign currency for contractAmount. |
originalAmountForeignCurrency number,string,null | Foreign currency for originalAmount. |
approvedChangeOrdersForeignCurrency number,string,null | Foreign currency for approvedChangeOrders. |
previousApprovedChangeOrdersForeignCurrency number,string,null | Foreign currency for previousApprovedChangeOrders. |
completedWorkRetentionForeignCurrency number,string,null | Foreign currency for completedWorkRetention. |
materialsRetentionForeignCurrency number,string,null | Foreign currency for materialsRetentionForeign. |
previousRetentionForeignCurrency number,string,null | Foreign currency for previousRetention. |
previousMaterialsBilledForeignCurrency number,string,null | Foreign currency for previousMaterialsBilled. |
recipients array: object | Persons that the generated documents will be sent to. |
id string | This is the ID of a user managed by BIM 360 Admin. |
isDefault boolean | True if this is the default recipient of a Contract or Change Order. |
netAmountForeignCurrency number,string,null | Foreign currency for netAmount. |
claimedAmount number,string,null | The claimed work completed for the payment. |
previousClaimedAmount number,string,null | The previous claimed work completed of the payment. |
architectCompanyId string,null | The BIM360/ACC ID of the architecture firm. The detailed company information can be retrieved from GET projects/:project_id/companies endpoint by searching the member_group_id in the response. |
architectCompanyUid string,null | The unique ID of the architecture firm. The detailed company information can be retrieved by this uuid from GET companies/:company_id <en/docs/bim360/v1/reference/http/companies-:company_id-GET/> in the response |
architectContactId string,null | The BIM360/ACC ID of the primary contact at the architecture firm. |
additionalCollaborators array: object | The additional collaborator company and contacts. |
companyId string | The BIM360/ACC ID of the firm. |
companyUid string,null | The unique ID (UUID) of the company in this account. Detailed company information can be retrieved using this UUID by calling GET companies/:company_id in the response. |
contactIds array: string | The BIM360/ACC user ID of the contacts in the firm. |
integrationState string,null | The state of the item during the integration with the external ERP system (such as SignNow). An item can be a budget , contract , main contract , main contract item , cost item , expense , expense item , change order , or schedule of value . For more details, see Integrate with External System tutorial.
Possible values:
For more information regarding integrations within the Cost Management system, see Integrations in Cost Management. |
integrationStateChangedAt string,null | The date and time that the item’s integration status was last changed. |
integrationStateChangedBy string,null | The user who last changed the integration status. This is the ID of a user managed by the BIM 360/ACC Admin. |
externalId string | The identifier assigned to an item in its original external ERP system. Use this ID to track and look up data within the integrated system. Note that this value comes from the item’s ID in the external system.
Max length: 255 |
externalSystem string | The name of the external ERP system integrated with Cost Management. Use this name to identify and search for data within the integrated system.
Max length: 255 |
externalMessage string | A message generated by the external ERP system that explains the sync status of the integration. For example, common values include success or fail to indicate the result of the integration operation.
Max length: 255 |
lastSyncTime datetime: ISO 8601 | The date and time when the item was last synchronized with the external ERP system. This value is updated by the external system and is in ISO 8601 format. |
createdAt datetime: ISO 8601 | The date and time that the item was created, in ISO 8601 format. |
updatedAt datetime: ISO 8601 | The date and time that the item was last updated, in ISO 8601 format. |
Example
Success
Request
curl -v 'https://developer.api.autodesk.com/cost/v1/containers/e94b9bc8-1775-4d76-9b1d-c613e120ccff/payments/:id' \
-H 'Authorization: Bearer AuIPTf4KYLTYGVnOHQ0cuolwCW2a'
Response
[
{
"id": "a2e16076-d5bb-44b3-b451-fb1fb390e4fc",
"billingPeriodId": "18d97ae0-9484-11e8-a7ec-7ddae203e404",
"previousPaymentId": "18d97ae0-9484-11e8-a7ec-7ddae203e404",
"associationId": "18d97ae0-9484-11e8-a7ec-7ddae203e404",
"mainContractId": "18d97ae0-9484-11e8-a7ec-7ddae203e404",
"budgetPaymentId": "18d97ae0-9484-11e8-a7ec-7ddae203e404",
"associationType": "Contract",
"startDate": "2019-02-01",
"endDate": "2019-02-28",
"dueDate": "2019-02-28",
"number": "09871000072000O",
"name": "INSURANCE",
"description": "Description of Payment",
"note": "",
"approvedAt": "2019-02-05T01:00:12.989Z",
"calculatedAt": "2019-02-05T01:00:12.989Z",
"calculatedBy": "CED9LVTLHNXV",
"companyId": "GF8XKPKWM38E",
"companyUid": "683904a0-47ce-4146-ac2d-a3840f00e0f4",
"contactId": "CED9LVTLHNXV",
"creatorId": "CED9LVTLHNXV",
"status": "draft",
"paidAt": "2019-02-05T01:00:12.989Z",
"forecastDistributionAt": "2019-02-05T01:00:12.989Z",
"submittedAt": "2019-02-05T01:00:12.989Z",
"contractAmount": "1000.0000",
"originalAmount": "1000.0000",
"amount": "1000.0000",
"previousAmount": "1000.0000",
"currentCompletedWorkRetentionPercent": "",
"completedWorkRetainedPercent": "",
"completedWorkRetention": "1000.0000",
"completedWorkGrossRetentionPercent": "",
"currentMaterialsRetentionPercent": "",
"materialsOnStoreRetention": "1000.0000",
"materialsRetention": "1000.0000",
"materialsGrossRetentionPercent": "",
"materialsRetainedPercent": "",
"totalGrossRetentionPercent": "",
"totalRetainedPercent": "",
"previousRetention": "1000.0000",
"netRetention": "1000.0000",
"materialsOnStore": "1000.0000",
"previousMaterialsOnStore": "1000.0000",
"materialsBilled": "1000.0000",
"previousMaterialsBilled": "1000.0000",
"netMaterialsOnStore": "1000.0000",
"approvedChangeOrders": "1000.0000",
"previousApprovedChangeOrders": "1000.0000",
"netAmount": "1000.0000",
"advanceAmount": "1000.0000",
"advancePercent": "",
"previousAdvanceAmount": "1000.0000",
"previousAdvanceAmountForeignCurrency": "1000.0000",
"recoupmentAmount": "1000.0000",
"recoupmentPercentOfCompletedWork": "",
"previousRecoupmentAmount": "1000.0000",
"previousRecoupmentAmountForeignCurrency": "1000.0000",
"aggregateBy": "workCompleted",
"hasItemRejected": true,
"hasItemReviewed": true,
"exchangeRate": "1.0000",
"previousExchangeRate": "1.0000",
"previousAmountForeignCurrency": "1000.0000",
"previousClaimedAmountForeignCurrency": "1000.0000",
"contractAmountForeignCurrency": "1000.0000",
"originalAmountForeignCurrency": "1000.0000",
"approvedChangeOrdersForeignCurrency": "1000.0000",
"previousApprovedChangeOrdersForeignCurrency": "1000.0000",
"completedWorkRetentionForeignCurrency": "1000.0000",
"materialsRetentionForeignCurrency": "1000.0000",
"previousRetentionForeignCurrency": "1000.0000",
"previousMaterialsBilledForeignCurrency": "1000.0000",
"recipients": [
{
"id": "ZPYARKZX9ANQ",
"isDefault": false
}
],
"netAmountForeignCurrency": "1000.0000",
"claimedAmount": "1000.0000",
"previousClaimedAmount": "1000.0000",
"architectCompanyId": "GF8XKPKWM38E",
"architectCompanyUid": "683904a0-47ce-4146-ac2d-a3840f00e0f4",
"architectContactId": "CED9LVTLHNXV",
"additionalCollaborators": [
{
"companyId": "GF8XKPKWM38E",
"companyUid": "683904a0-47ce-4146-ac2d-a3840f00e0f4",
"contactIds": [
"CED9LVTLHNXV"
]
}
],
"integrationState": "locked",
"integrationStateChangedAt": "2019-09-05T01:00:12.989Z",
"integrationStateChangedBy": "CED9LVTLHNXV",
"externalId": "10010-99-AB",
"externalSystem": "Sage300",
"externalMessage": "Success.",
"lastSyncTime": "2019-09-05T01:00:12.989Z",
"createdAt": "2019-01-06T01:24:22.678Z",
"updatedAt": "2019-09-05T01:00:12.989Z"
}
]