Request

Response

    Payment Items
    GET

    v1/containers/{containerId}/payment-items

    Retrieves payment items in the given project based on associationId and paymentId.

    Note that this endpoint is compatible with both BIM 360 and Autodesk Construction Cloud (ACC) projects.

    Resource Information
    Method and URI
    GET
     https://developer.api.autodesk.com/cost/v1/containers/:containerId/payment-items
    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: EMEA, US. For the full list of supported regions, see the Regions page.

    * Required

    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.

    Request

    Query String Parameters
    filter[associationId]
    array: string: uuid
    		Return only the payment items that are associated with the provided list of contract or main contract IDs. Separate multiple IDs with commas. For example, filter[associationId]=id1,id2.
    filter[paymentId]
    array: string: uuid
    		Return only the payment items that are associated with the payments identified by the provided list of payment IDs. Separate multiple IDs with commas. For example, filter[id]=id1,id2.
    filter[associationType]
    array: string
    		Return only the payment items that are associated with the type of original entities specified. For example, filter[associationType]=SOV,SCO. Possible values for cost payment: SOV,SCO,CostItem,MaterialsOnSite, and budget payments: MainContractItem,OCO,CostItem,SubCostItem,MaterialsOnSite.
    offset
    int
    		The number of objects to skip before returning a page of records. To return the subsequent page, increment this number by the value of limit in the next request.
    limit
    int
    		The maximum number of records that this endpoint returns per page. Default: 100.

    Note that a returned page may contain fewer items than the limit under either of these conditions:

    • There are fewer items found than the limit value.
    • The last page of a set is returned.
    sort
    string
    		The sort order for items. Each attribute can be sorted in either asc (default) or desc order. For example, sort=name, updatedAt desc or sort=name + updatedAt desc sorts the results first by name in ascending order, then by date updated in descending order.

    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)
    Expand all
    pagination
    object
    		Pagination information when data must be returned page by page.
    limit
    int
    		The maximum number of objects returned in this response.
    offset
    int
    		The number of resulting objects that were skipped before this page of records was returned.
    totalResults
    int
    		The total number of objects found that satisfied the request criteria.
    nextUrl
    string
    		The URL for the next request to return the next page of records.

    Max length: 2000

    results
    array: object
    		The detail items in the payment.
    id
    string: UUID
    		Unique identifier of the payment.
    paymentId
    string: UUID
    		The ID of the payment the items belong to.
    parentId
    string: UUID
    		The ID of the parent item for sub items.
    budgetId
    string: UUID
    		The ID of the Budget to which the payment item belongs.
    associationType
    enum:string
    		The object type of the payment item is generated from. Possible values: SCO, OCO, SOV, CostItem, SubCostItem, MaterialsOnSite
    associationId
    string: UUID
    		The ID of the object that the payment item is generated from.
    name
    string
    		The name of the payment item.

    Max length: 1024

    description
    string
    		A description of the payment item.
    originalQuantity
    number
    		The original quantity of the payment item.
    originalUnitPrice
    number,string,null
    		The original unit price of the payment item.
    originalAmount
    number,string,null
    		The original amount of the payment item.
    quantity
    number
    		The actual quantity of payment item in this payment.
    unitPrice
    number,string,null
    		The unit price of payment item in this payment.
    unit
    string
    		The unit of measure of the payment item.
    amount
    number,string,null
    		The work completed amount of payment item in this payment.
    previousAmount
    number,string,null
    		The total amount of the work completed that has been paid previously.
    previousQuantity
    number
    		The total quantity that has been paid previously.
    previousUnitPrice
    number,string,null
    		The average unit price that has been paid previously.
    materialsOnStore
    number,string,null
    		The amount of the material currently on site.
    materialsOnStoreQuantity
    number
    		The quantity of the material currently on site.
    materialsOnStoreUnit
    string
    		The unit of measure of the material currently on site.
    materialsOnStoreUnitPrice
    number,string,null
    		The unit price of the material currently on site.
    previousMaterialsOnStore
    number,string,null
    		The amount of the material on site in last payment.
    materialsBilled
    number,string,null
    		The amount of the material that will be billed in this period.
    materialsBilledQuantity
    number
    		The quanity of the material that will be billed in this period.
    materialsBilledUnit
    string
    		The unit of meaure of the material that will be billed in this period.
    materialsBilledUnitPrice
    number,string,null
    		The unit price of the material that will be billed in this period.
    previousMaterialsBilled
    number,string,null
    		The amount of the material billed in previous payments.
    previousMaterialsBilledUnitPrice
    number,string,null
    		The unit price of the material billed in previous payment.
    previousMaterialsBilledQuantity
    number
    		The quantity of the material billed in previous payment.
    previousMaterialsBilledUnit
    string
    		The unit of the material billed in previous payment.
    completedWorkRetention
    number,string,null
    		The total amount of work to be retained.
    completedWorkRetentionPercent
    number
    		The percentage the total amount of work to be retained.
    completedWorkReleased
    number,string,null
    		The amount that is released in this payment for work completed.
    materialsOnStoreRetentionPercent
    number
    		The percentage the total amount of material to be retained. This parameter is deprecated, use materialsRetentionPercent.
    materialsRetention
    number,string,null
    		The total amount of material to be retained.
    materialsRetentionPercent
    number
    		The percentage the total amount of material to be retained.
    totalRetentionPercent
    number
    		The total amount of work and material to be retained.
    materialsOnStoreReleased
    number,string,null
    		The amount the material that is released in this payment. This parameter is deprecated, use materialsReleased.
    materialsReleased
    number,string,null
    		The amount the material that is released in this payment.
    netAmount
    number,string,null
    		The net amount that should be paid in this period, including work completed, material on site or billed, 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.
    creatorId
    string,null
    		The user who created the payment item. This is the ID of a user managed by BIM 360 Admin.
    changedBy
    string,null
    		The user who made the change.
    lastReviewedBy
    string,null
    		The last user who made the review.
    canDelete
    boolean
    		Indicate if this payment item can be deleted.
    isPrivate
    boolean,null
    		Indicate if this payment item should be exposed to owner. This is only for budget payment.
    status
    string,null
    		The review status the item. Possible values: accepted, rejected, semi-rejected, null
    hasComment
    boolean
    		Indicate if this payment item has comment.
    aggregateBy
    string,null
    		The aggregate type to budget Payment application. Possible values: workCompleted, workCompletedPercentage
    exchangeRate
    number,string,null
    		Exchange rate. Default value is 1. If multi-currency is not enabled, it will also be 1.
    originalExchangeRate
    number,string,null
    		If this payment item came from Schedule of Value, the value is equal to Schedule of Value exchange rate; If this payment item came from SCO, the value is equal to SCO 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.
    netAmountForeignCurrency
    number,string,null
    		Foreign currency for netAmount.
    realizedGainOrLoss
    number,string,null
    		netAmountForeignCurrency / originalExchangeRate - netAmount
    claimedQuantity
    number,string,null
    		The claimed work completed qty of the payment item.
    claimedUnitPrice
    number,string,null
    		The claimed work completed unit price of the payment item.
    claimedAmount
    number,string,null
    		The claimed work completed amount of the payment item.
    previousClaimedQuantity
    number,string,null
    		The previous claimed work completed qty of the payment item.
    previousClaimedUnitPrice
    number,string,null
    		The previous claimed work completed unit price of the payment item.
    previousClaimedAmount
    number,string,null
    		The previous claimed work completed amount of the payment item.
    previousClaimedAmountForeignCurrency
    number,string,null
    		The foreign currency for the previousClaimedAmount.
    previousMaterialsBilledForeignCurrency
    number,string,null
    		The foreign currency for the previousMaterialsBilled.
    position
    int
    		The position of the payment item in the payment item siblings.
    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.
    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.
    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:

    locked: the item is currently locked within the ERP system, preventing modifications until unlocked. To unlock and modify the item, use the relevant PATCH endpoint to set integrationState to null. For example, for a budget, call PATCH budgets. For a contract, call PATCH contracts. For more details, see the Help documentation.

    integrated: the item has been successfully added to the ERP system.

    failed: the item encountered an error during the integration process and was not successfully added to the ERP system. For example, if a user tries to integrate contracts from an ERP system and the updates fail, the integrationState can be set to failed. Retry the sync process or analyze the issue if it continues to fail.

    null: The item has not been integrated with the ERP system. This is default value.

    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.

    Example

    Success

    Request

    curl -v 'https://developer.api.autodesk.com/cost/v1/containers/e94b9bc8-1775-4d76-9b1d-c613e120ccff/payment-items?limit=100&sort=name,createdAt desc' \
  -H 'Authorization: Bearer AuIPTf4KYLTYGVnOHQ0cuolwCW2a'

    Response

    {
  "pagination": {
    "limit": 20,
    "offset": 0,
    "totalResults": 1,
    "nextUrl": ""
  },
  "results": [
    {
      "id": "a2e16076-d5bb-44b3-b451-fb1fb390e4fc",
      "paymentId": "18d97ae0-9484-11e8-a7ec-7ddae203e404",
      "parentId": "18d97ae0-9484-11e8-a7ec-7ddae203e404",
      "budgetId": "48934441-e392-49d7-bf58-8dea43d413ae",
      "associationType": "Contract",
      "associationId": "18d97ae0-9484-11e8-a7ec-7ddae203e404",
      "name": "INSURANCE",
      "description": "The description of the payment item.",
      "originalQuantity": "10,000",
      "originalUnitPrice": "1000.0000",
      "originalAmount": "1000.0000",
      "quantity": 100,
      "unitPrice": "1000.0000",
      "unit": "LS",
      "amount": "1000.0000",
      "previousAmount": "1000.0000",
      "previousQuantity": "2,000",
      "previousUnitPrice": "1000.0000",
      "materialsOnStore": "1000.0000",
      "materialsOnStoreQuantity": 100,
      "materialsOnStoreUnit": "LS",
      "materialsOnStoreUnitPrice": "1000.0000",
      "previousMaterialsOnStore": "1000.0000",
      "materialsBilled": "1000.0000",
      "materialsBilledQuantity": 100,
      "materialsBilledUnit": "LS",
      "materialsBilledUnitPrice": "1000.0000",
      "previousMaterialsBilled": "1000.0000",
      "previousMaterialsBilledUnitPrice": "1000.0000",
      "previousMaterialsBilledQuantity": 100,
      "previousMaterialsBilledUnit": "LS",
      "completedWorkRetention": "1000.0000",
      "completedWorkRetentionPercent": "0.3",
      "completedWorkReleased": "1000.0000",
      "materialsOnStoreRetentionPercent": "0.1",
      "materialsRetention": "1000.0000",
      "materialsRetentionPercent": "0.1",
      "totalRetentionPercent": "0.2",
      "materialsOnStoreReleased": "1000.0000",
      "materialsReleased": "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",
      "creatorId": "CED9LVTLHNXV",
      "changedBy": "CED9LVTLHNXV",
      "lastReviewedBy": "CED9LVTLHNXV",
      "canDelete": true,
      "isPrivate": false,
      "status": "rejected",
      "hasComment": true,
      "aggregateBy": "workCompleted",
      "exchangeRate": "1.0000",
      "originalExchangeRate": "1.0000",
      "previousExchangeRate": "1.0000",
      "previousAmountForeignCurrency": "1000.0000",
      "netAmountForeignCurrency": "1000.0000",
      "realizedGainOrLoss": "1000.0000",
      "claimedQuantity": "1000.0000",
      "claimedUnitPrice": "1000.0000",
      "claimedAmount": "1000.0000",
      "previousClaimedQuantity": "1000.0000",
      "previousClaimedUnitPrice": "1000.0000",
      "previousClaimedAmount": "1000.0000",
      "previousClaimedAmountForeignCurrency": "1000.0000",
      "previousMaterialsBilledForeignCurrency": "1000.0000",
      "position": 1,
      "createdAt": "2019-01-06T01:24:22.678Z",
      "updatedAt": "2019-09-05T01:00:12.989Z",
      "externalId": "10010-99-AB",
      "externalSystem": "Sage300",
      "externalMessage": "Success.",
      "lastSyncTime": "2019-09-05T01:00:12.989Z",
      "integrationState": "locked",
      "integrationStateChangedAt": "2019-09-05T01:00:12.989Z",
      "integrationStateChangedBy": "CED9LVTLHNXV"
    }
  ]
}
    Show More