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 a three-legged access token obtained via an Authorization Code flow or a Secure Service Account (SSA) flow.
The SSA flow is designed for headless server-to-server operations. While it functions like a two-legged flow (no user interaction), it is classified as three-legged because it preserves user context. |
| region string | Specifies the region where the project data resides.
By default, the request is routed automatically. However, specifying the region can improve performance by avoiding lookup overhead. Possible values: country or region codes such as To verify your project’s region, refer to the Working with BIM 360 Services in Different Regions section on the API Basics page. |
Request
URI Parameters
| containerId string: UUID | The ID of the project (the container ID is the same as the project ID). To obtain the project ID, see 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. |
| associationType enum:string | The type of contract associated with this payment.
Possible values: |
| 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. |
| budgetTransferIds array: string | Not relevant |
| changeOrderIds array: string | Not relevant |
| totalApprovedChangeOrderAdditions number,string,null | Not relevant |
| totalApprovedChangeOrderAdditionsForeignCurrency number,string,null | Not relevant |
| totalApprovedChangeOrderDeductions number,string,null | Not relevant |
| totalApprovedChangeOrderDeductionsForeignCurrency number,string,null | Not relevant |
| 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. |
| 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: |
| 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 | Exchange rate from previous payment application. Default value is 1, if multi-currency is not enabled, it will also be 1. |
| contractAmount number,string,null | The original contract amount of the payment. |
| contractAmountForeignCurrency number,string,null | The original contract amount of the payment, in foreign currency. |
| approvedChangeOrders number,string,null | The amount of total approved change orders in this payment. |
| approvedChangeOrdersForeignCurrency number,string,null | The amount of total approved change orders in this payment, in foreign currency. |
| approvedBudgetTransfers number,string,null | Not relevant |
| approvedBudgetTransfersForeignCurrency number,string,null | Not relevant |
| originalAmount number,string,null | The original payment amount, including the main contract amount, change orders, and internal budget transfers that affect the schedule of values defined in project settings. |
| originalAmountForeignCurrency number,string,null | The original payment amount in foreign currency, including the main contract amount, change orders, and internal budget transfers that affect the schedule of values defined in project settings. |
| previousAmount number,string,null | The amount of total work completed prior to this period. |
| previousAmountForeignCurrency number,string,null | The amount of total work completed prior to this period, in foreign currency. |
| previousApprovedChangeOrders number,string,null | The amount of total approved change orders prior to this period. |
| previousApprovedChangeOrdersForeignCurrency number,string,null | The amount of total approved change orders prior to this period, in foreign currency. |
| previousApprovedBudgetTransfers number,string,null | Not relevant |
| previousApprovedBudgetTransfersForeignCurrency number,string,null | Not relevant |
| amount number,string,null | The amount of the work completed in this period. |
| previousMaterialsOnStore number,string,null | The amount of total materials stored prior to this period. |
| materialsOnStore number,string,null | The amount of the materials stored in this application. |
| previousMaterialsBilled number,string,null | The amount of total materials billed prior to this period. |
| previousMaterialsBilledForeignCurrency number,string,null | The amount of total materials billed prior to this period, in foreign currency. |
| materialsBilled number,string,null | The amount of the materials billed in this period. |
| currentCompletedWorkRetentionPercent number | Not relevant |
| completedWorkRetainedPercent number | Not relevant |
| completedWorkRetained number | Not relevant |
| completedWorkRetention number,string,null | The amount of total work completed retained in this application. |
| completedWorkRetentionForeignCurrency number,string,null | The amount of total work completed retained (pre-release), in foreign currency. |
| completedWorkGrossRetentionPercent number | The percentage of the gross retention amount of the payment for work completed. (released value is not removed) |
| currentMaterialsRetentionPercent number | Not relevant |
| materialsGrossRetentionPercent number | The percentage of the gross retention of the payment for material (released value is not removed). |
| materialsRetainedPercent number | Not relevant |
| materialsRetained number,string,null | The amount of the materials (stored or billed) retained in this application. |
| materialsRetention number,string,null | The amount of the materials (stored or billed) retained in this application. |
| materialsOnStoreRetention number,string,null | The amount of the materials stored retained in this application. This parameter is deprecated. |
| materialsRetentionForeignCurrency number,string,null | The amount of the materials (stored or billed) retained in this application, in foreign currency. |
| 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 |
| totalRetained number | Not relevant |
| previousRetention number,string,null | The retained amount of total work completed and materials (stored or billed) prior to this period. |
| previousRetentionForeignCurrency number,string,null | The retained amount of total work completed and materials (stored or billed) prior to this period, in foreign currency. |
| netAmount number,string,null | The net amount that should be paid in this period, including work completed, advance amount, materials stored or billed, retention and release. |
| netAmountForeignCurrency number,string,null | The net amount that should be paid in this period, including work completed, advance amount, materials stored or billed, retention and release, in foreign currency. |
| netMaterialsOnStore number,string,null | The net materials stored in this period, which equals to (materialsOnStore - previousMaterialsOnStore). |
| netRetention number,string,null | The net retention in this period, which equals to (completedWorkRetention + materialsOnStoreRetention - previousRetention). |
| previousClaimedAmount number,string,null | The claimed amount of total work completed prior to this period. |
| previousClaimedAmountForeignCurrency number,string,null | The claimed amount of total work completed prior to this period, in foreign currency. |
| claimedAmount number,string,null | The claimed amount of total work completed in this period. |
| previousAdvanceAmount number,string,null | The advance amount of total work completed prior to this period. |
| previousAdvanceAmountForeignCurrency number,string,null | The advance amount of total work completed prior to this period, in foreign currency. |
| previousRecoupmentAmount number,string,null | The recoupment amount of total work completed prior to this period. |
| previousRecoupmentAmountForeignCurrency number,string,null | The recoupment amount of total work completed prior to this period, in foreign currency. |
| advancePercent number,null | The advance percent of the work completed in this period. |
| advanceAmount number,string,null | The advance amount of the work completed in this period. |
| recoupmentAmount number,string,null | The recoupment amount of the work completed in this period. |
| recoupmentPercentOfCompletedWork number,null | The recoupment percentage of the work completed in this period. |
| aggregateBy string,null | Not relevant |
| canReleaseRetention boolean | Not relevant |
| isRetentionPercentPreserved boolean | 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. |
| 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. |
| 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 hub. Detailed company information can be retrieved using this UUID by calling GET companies/:company_id in the response. |
| architectCompanyId string,null | The BIM360/Forma 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/Forma ID of the primary contact at the architecture firm. |
| additionalCollaborators array: object | The additional collaborator company and contacts. |
| companyId string | The BIM360/Forma ID of the firm. |
| companyUid string,null | The unique ID (UUID) of the company in this hub. Detailed company information can be retrieved using this UUID by calling GET companies/:company_id in the response. |
| contactIds array: string | The BIM360/Forma user ID of the contacts in the firm. |
| 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. |
| 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. |
| paymentStage enum:string | Not relevant |
| paymentStageSource string,null | The source of the payment stage change. Possible values:
|
| migrationStatus enum:string | Not relevant |
| migrationUpdatedAt string,null | Not relevant |
| bridgeInfo object,null | Not relevant |
| internalId string,null | Not relevant |
| internalSystem string,null | Not relevant |
| 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/Forma 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",
"associationType": "Contract",
"associationId": "18d97ae0-9484-11e8-a7ec-7ddae203e404",
"mainContractId": "18d97ae0-9484-11e8-a7ec-7ddae203e404",
"budgetPaymentId": "18d97ae0-9484-11e8-a7ec-7ddae203e404",
"budgetTransferIds": [
"a2e16076-d5bb-44b3-b451-fb1fb390e4fc"
],
"changeOrderIds": [
"a2e16076-d5bb-44b3-b451-fb1fb390e4fc"
],
"totalApprovedChangeOrderAdditions": "1000.0000",
"totalApprovedChangeOrderAdditionsForeignCurrency": "1000.0000",
"totalApprovedChangeOrderDeductions": "1000.0000",
"totalApprovedChangeOrderDeductionsForeignCurrency": "1000.0000",
"startDate": "2019-02-01",
"endDate": "2019-02-28",
"dueDate": "2019-02-28",
"number": "09871000072000O",
"name": "INSURANCE",
"description": "Description of Payment",
"note": "",
"contactId": "CED9LVTLHNXV",
"creatorId": "CED9LVTLHNXV",
"status": "draft",
"exchangeRate": "1.0000",
"previousExchangeRate": "1.0000",
"contractAmount": "1000.0000",
"contractAmountForeignCurrency": "1000.0000",
"approvedChangeOrders": "1000.0000",
"approvedChangeOrdersForeignCurrency": "1000.0000",
"approvedBudgetTransfers": "1000.0000",
"approvedBudgetTransfersForeignCurrency": "1000.0000",
"originalAmount": "1000.0000",
"originalAmountForeignCurrency": "1000.0000",
"previousAmount": "1000.0000",
"previousAmountForeignCurrency": "1000.0000",
"previousApprovedChangeOrders": "1000.0000",
"previousApprovedChangeOrdersForeignCurrency": "1000.0000",
"previousApprovedBudgetTransfers": "1000.0000",
"previousApprovedBudgetTransfersForeignCurrency": "1000.0000",
"amount": "1000.0000",
"previousMaterialsOnStore": "1000.0000",
"materialsOnStore": "1000.0000",
"previousMaterialsBilled": "1000.0000",
"previousMaterialsBilledForeignCurrency": "1000.0000",
"materialsBilled": "1000.0000",
"currentCompletedWorkRetentionPercent": 0.1,
"completedWorkRetainedPercent": 0.1,
"completedWorkRetained": "",
"completedWorkRetention": "1000.0000",
"completedWorkRetentionForeignCurrency": "1000.0000",
"completedWorkGrossRetentionPercent": 0.1,
"currentMaterialsRetentionPercent": 0.1,
"materialsGrossRetentionPercent": 0.1,
"materialsRetainedPercent": 0.1,
"materialsRetained": "1000.0000",
"materialsRetention": "1000.0000",
"materialsOnStoreRetention": "1000.0000",
"materialsRetentionForeignCurrency": "1000.0000",
"totalGrossRetentionPercent": 0.1,
"totalRetainedPercent": 0.1,
"totalRetained": "",
"previousRetention": "1000.0000",
"previousRetentionForeignCurrency": "1000.0000",
"netAmount": "1000.0000",
"netAmountForeignCurrency": "1000.0000",
"netMaterialsOnStore": "1000.0000",
"netRetention": "1000.0000",
"previousClaimedAmount": "1000.0000",
"previousClaimedAmountForeignCurrency": "1000.0000",
"claimedAmount": "1000.0000",
"previousAdvanceAmount": "1000.0000",
"previousAdvanceAmountForeignCurrency": "1000.0000",
"previousRecoupmentAmount": "1000.0000",
"previousRecoupmentAmountForeignCurrency": "1000.0000",
"advancePercent": 0.1,
"advanceAmount": "1000.0000",
"recoupmentAmount": "1000.0000",
"recoupmentPercentOfCompletedWork": 0.1,
"aggregateBy": "workCompleted",
"canReleaseRetention": false,
"isRetentionPercentPreserved": false,
"hasItemRejected": true,
"hasItemReviewed": true,
"recipients": [
{
"id": "ZPYARKZX9ANQ",
"isDefault": false
}
],
"companyId": "GF8XKPKWM38E",
"companyUid": "683904a0-47ce-4146-ac2d-a3840f00e0f4",
"architectCompanyId": "GF8XKPKWM38E",
"architectCompanyUid": "683904a0-47ce-4146-ac2d-a3840f00e0f4",
"architectContactId": "CED9LVTLHNXV",
"additionalCollaborators": [
{
"companyId": "GF8XKPKWM38E",
"companyUid": "683904a0-47ce-4146-ac2d-a3840f00e0f4",
"contactIds": [
"CED9LVTLHNXV"
]
}
],
"approvedAt": "2019-02-05T01:00:12.989Z",
"calculatedAt": "2019-02-05T01:00:12.989Z",
"calculatedBy": "CED9LVTLHNXV",
"paidAt": "2019-02-05T01:00:12.989Z",
"forecastDistributionAt": "2019-02-05T01:00:12.989Z",
"submittedAt": "2019-02-05T01:00:12.989Z",
"paymentStage": "Progress",
"paymentStageSource": "user",
"migrationStatus": "not_migrated",
"migrationUpdatedAt": "2019-02-05T01:00:12.989Z",
"bridgeInfo": "",
"internalId": "123",
"internalSystem": "GCPay",
"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"
}
]