Budget Adjustments

This resource is used to add budget adjustments. Each budget item detail may have one or more budget adjustments and adjustments can be made to manually add or subtract the budget, spent or pending balances.

Create a Budget Adjustment

Create one or more budget adjustments.

  • If the rolling adjustment feature is used, all adjustments for a given month, adjustment type, amount type, budget, and description will be combined into one adjustment. See Parameters below.
  • The combination of budget item name, fiscal year name, fiscal period name, and owner email determine which budget the adjustment affects. See Schema below
  • The amount type determines how the adjustment affects the budget. The budget amount adjustment reduces or increases the top-line budget amount while spent and pending amounts affect the budget balances.
  • Adjustments may not be deleted or updated via the API.

Scopes

budgetitem.write - Refer to Scope Usage for full details.

Request

URI

Template
POST /budget/v4/adjustments

Parameters

Name Type Format Description
useMonthlyRollingUpdate boolean query Required If true, all adjustments for a given month, adjustment type, amount type & description will be rolled up to one adjustment. This is useful for an automated process that makes daily or weekly updates and doesn’t want to clutter end-user dashboards.

Headers

Payload

Budget Adjustments

Response

Status Codes

  • 200 OK Successful call, response is in body.
  • 400 Bad Request The request was determined to be invalid by the server. Possibly a validation failed on the data that was sent in the payload. The response will have a list of validation errors in the body. See below for an example 400 response.
  • 403 Forbidden The user does not have the necessary permissions to perform the request.
  • 404 Not Found The resource could not be found or does not exist.
  • 500 Internal Server Error Error message in response body.
  • 504 Gateway Timeout Error message in response body.

Headers

Payload

Either “Success” or an Error Response

Example

Request

POST https://us.api.concursolutions.com/budget/v4/adjustments?useMonthlyRollingUpdate=false
Authorization: Bearer {token}
Content-Type: application/json
Accept: application/json
[
	{
		"budgetItemName":"API Budget-Oregon",
		"fiscalYearName": "2018",
		"budgetOwnerEmail": "m.jones@example.com",
		"fiscalPeriodName": "2018 - Q3",
		"amount": 100,
		"adjustmentType": "FUND_TRANSFER",
		"amountType": "BUDGET_AMOUNT",
		"description": "Initial July Adjustment",
		"transactionDate": "2018-07-11"
	},
	{
		"budgetItemName":"API Budget-Travel",
		"fiscalYearName": "2018",
		"budgetOwnerEmail": "m.jones@example.com",
		"fiscalPeriodName": "2018 - Q3",
		"amount": 100,
		"adjustmentType": "EXPENSE",
		"amountType": "SPENT_AMOUNT",
		"transactionDate": "2018-07-10"
	},
  	{
		"budgetItemName":"API Budget-Travel",
		"fiscalYearName": "2018",
		"budgetOwnerEmail": "m.jones@example.com",
		"fiscalPeriodName": "2018 - Q3",
		"amount": 100,
		"adjustmentType": "EXPENSE",
		"amountType": "SPENT_AMOUNT",
		"transactionDate": "2018-07-10",
    "budgetItemHeaderId":"72eee673-3d81-49c2-966a-b63c7a9302e6"
	}
]

Response

Success Response
HTTP/1.1 200 OK
Cache-Control: no-store
Connection: keep-alive
Content-Length: 9
Content-Type: application/json;charset=utf-8
Date: Fri, 21 Sep 2018 15:24:27 GMT
Expires: Thu, 20 Sep 2018 15:24:27 GMT
Pragma: no-cache
Vary: Origin
concur-correlationid: 86a0d9fe-9e98-43c3-89d8-a2917dd844cb
"Success"
Failure Response
HTTP/1.1 400 Bad Request
Cache-Control: no-store
Connection: close
Content-Length: 242
Content-Type: application/json;charset=utf-8
Date: Fri, 21 Sep 2018 15:29:05 GMT
Expires: Thu, 20 Sep 2018 15:29:05 GMT
Pragma: no-cache
concur-correlationid: 561ce34c-6542-4bae-82a2-aa6ccd8c6b22
{
    "message": {  
        "status" : false,
        "errorMessageList" : [
          {
            "errorType" : "ERROR",
            "errorCode" : "BUDGET.BUDGET_PERIOD_REQUIRED",
            "errorMessage" : "Record 1) Record 1) Budget period is missing"
          }
        ]
    }
}

Schema

Budget Adjustment

Name Type Format Description
budgetItemName string - Required The name of the budget of the adjustment.
fiscalYearName string - Required The name of the budget’s fiscal year. The default name for a fiscal year is the numeric, four-digit year. For DateRange budgets the value needs to be DateRangeFY. Example: 2019
fiscalPeriodName string - Required The specific fiscal period when this budget amount will be used. The default name for a fiscal period is: Monthly: <fiscal year name> - <three-letter month abbreviation> (Example: 2019 - Jun). Quarterly: <fiscal year name> - Q<number of quarter> (Example: 2019 - Q2). Yearly: <fiscal year name> For DateRange budgets the value needs to be [period start - period end].(Example: 2019, 2021-10-01 - 2022-09-30).
budgetOwnerEmail string - Required The user who is responsible for the budget, as configured.
amount decimal - Required The budget currency amount to be adjusted. The amount may be a positive or negative value but it cannot be zero.
adjustmentType string - Required The type of adjustment being made. Only a user reference field. Supported values: BUDGET_BALANCE, FUND_TRANSFER, EXPENSE, PAYMENT_REQUEST, PURCHASE_REQUEST, REQUEST
amountType string - Required The type of the budget’s balance to adjust. Affects which values in the budget are updated. Supported values: BUDGET_AMOUNT, SPENT_AMOUNT, PENDING_AMOUNT
description string - A user-friendly description of the adjustment.
transactionDate date YYYY-MM-DD Required if amount type is either SPENT_AMOUNT or PENDING_AMOUNT The transaction date of adjusted spend. Must be within the fiscal period.
budgetItemHeaderId string - The unique ID of the Budget Item header of the adjustment. When provided optimizes API performance and response time. Note: budgetItemHeaderId takes precedence over budgetItemName and budgetOwnerEmail values.

Error Response

Name Type Format Description
status boolean - False if there was an error.
errorMessageList array errorMessage List of all errors detected.

Error Message

Name Type Format Description
errorType string - WARNING or ERROR.
errorCode string - Text code for this error.
errorMessage string - Plain language error message.

On this page