API v1 Reference › Retainers

Updates the specified project retainer.

PUThttps://api.awork.com/api/v1/projects/{projectId}/retainers/{retainerId}
PUT https://api.awork.com/api/v1/projects/{projectId}/retainers/{retainerId}

Updates the retainer settings. Date changes cannot overlap another retainer, and the retainer period cannot be changed.

Authentication

AuthorizationBearer

Send your token in the Authorization: Bearer <token> header. See Authentication for API keys and OAuth.

Path parameters

projectIdstringRequired
format: uuid

The id of the project to update the retainer for.

retainerIdstringRequired
format: uuid

The id of the retainer.

Request body Required

The model to update the retainer.

application/json

timeBudgetintegerOptional
format: int32

The time budget per retainer period in seconds. The default budget amount for new budgets in this retainer.

timezonestring or nullOptional

The timezone for when new budgets are created.

rollOverUnderspentBudgetbooleanOptional

Whether underspent budgets should be rolled over to the next period.

rollOverOverspentBudgetbooleanOptional

Whether overspent budgets should be rolled over to the next period.

startDatestringOptional
format: date-time

The start of the retainer contract.

endDatestring or nullOptional
format: date-time

The end of the retainer contract until new budgets will be created. Optional.

syncProjectDatesbooleanOptional

Whether the project start and due dates should be synced to the retainer start and end dates.

Responses

200 OK

application/json

timeBudgetintegerOptional
format: int32

The time budget per retainer period in seconds. The default budget amount for new budgets in this retainer.

timezonestring or nullOptional

The timezone for when new budgets are created.

rollOverUnderspentBudgetbooleanOptional

Whether underspent budgets should be rolled over to the next period.

rollOverOverspentBudgetbooleanOptional

Whether overspent budgets should be rolled over to the next period.

startDatestringOptional
format: date-time

The start of the retainer contract.

endDatestring or nullOptional
format: date-time

The end of the retainer contract until new budgets will be created. Optional.

syncProjectDatesbooleanOptional

Whether the project start and due dates should be synced to the retainer start and end dates.

idstringOptional
format: uuid

The id of the retainer.

retainerPeriodstring or nullOptional

The period for new budgets in this retainer. Currently only 'monthly' is supported.

projectIdstringOptional
format: uuid

The project this retainer is associated with.

isExternalbooleanOptional

Whether the retainer belongs to an external project.

retainerBudgetsarray of object or nullOptional

The budgets for this retainer. Each budget period (month) gets its own budget.

Show 5 properties
idstringOptional
format: uuid

The id of the retainer budget.

timeBudgetintegerOptional
format: int32

The budget for this retainer period in seconds. Based on the carry over option selected in the retainer settings, the timebudget is adjusted by the carry over from the previous period.

trackedDurationintegerOptional
format: int32

The sum of tracked time in this retainer period. Contains billable and non-billable hours if the DeductNonBillableHours flag is set to true. Contains only billable hours if the DeductNonBillableHours flag is set to false. Time entries belong to the retainer period if their StartDate is between the StartDate and EndDate of the retainer period.

startDatestringOptional
format: date-time

The start of the retainer period in UTC.

endDatestringOptional
format: date-time

The end of the retainer period in UTC.

createdOnstringOptional
format: date-time

The date this retainer was created.

createdBystringOptional
format: uuid

The id of the user who created this retainer.

updatedOnstringOptional
format: date-time

The date this retainer was last modified.

updatedBystringOptional
format: uuid

The id of the user who last modified this retainer.

400 Bad Request

application/json

codestringRequired
minLength: 1

The error code.

descriptionstringRequired
minLength: 1

The description of the error.

linkstringRequired
minLength: 1

The link to the API documentation page.

detailsarray of string or nullOptional

A list of details describing the error.

validationErrorsarray of object or nullOptional

If a validation error occurred, this contains the validation errors for each property.

Show 2 properties
propertystring or nullOptional

The name of the property that failed validation.

messagestring or nullOptional

The reason why this property failed validation.

traceIdstring or nullOptional

The request trace id for tracking the request.

404 Not Found

application/json

codestringRequired
minLength: 1

The error code.

descriptionstringRequired
minLength: 1

The description of the error.

linkstringRequired
minLength: 1

The link to the API documentation page.

detailsarray of string or nullOptional

A list of details describing the error.

validationErrorsarray of object or nullOptional

If a validation error occurred, this contains the validation errors for each property.

Show 2 properties
propertystring or nullOptional

The name of the property that failed validation.

messagestring or nullOptional

The reason why this property failed validation.

traceIdstring or nullOptional

The request trace id for tracking the request.

Search documentation