Budgets - Create Or Update

Service:: Consumption

API Version:: 2024-08-01

The operation to create or update a budget. You can optionally provide an eTag if desired as a form of concurrency control. To obtain the latest eTag for a given budget, perform a get operation prior to your put operation.

PUT https://management.azure.com/{scope}/providers/Microsoft.Consumption/budgets/{budgetName}?api-version=2024-08-01

URI Parameters

Name	In	Required	Type	Description
budgetName	path	True	string	Budget Name.
scope	path	True	string	The fully qualified Azure Resource manager identifier of the resource.
api-version	query	True	string minLength: 1	The API version to use for this operation.

Request Body

Name	Required	Type	Description
properties.amount	True	number (decimal)	The total amount of cost to track with the budget
properties.category	True	CategoryType	The category of the budget, whether the budget tracks cost or usage.
properties.timeGrain	True	TimeGrainType	The time covered by a budget. Tracking of the amount will be reset based on the time grain. BillingMonth, BillingQuarter, and BillingAnnual are only supported by WD customers
properties.timePeriod	True	BudgetTimePeriod	Has start and end date of the budget. The start date must be first of the month and should be less than the end date. Budget start date must be on or after June 1, 2017. Future start date should not be more than twelve months. Past start date should be selected within the timegrain period. There are no restrictions on the end date.
eTag		string	eTag of the resource. To handle concurrent update scenario, this field will be used to determine whether the user is updating the latest version or not.
properties.filter		BudgetFilter	May be used to filter budgets by user-specified dimensions and/or tags.
properties.notifications		<string, Notification>	Dictionary of notifications associated with the budget. Budget can have up to five notifications.

Responses

Name	Type	Description
200 OK	Budget	Resource 'Budget' update operation succeeded
201 Created	Budget	Resource 'Budget' create operation succeeded
Other Status Codes	ErrorResponse	An unexpected error response.

Security

azure_auth

Azure Active Directory OAuth2 Flow.

Type: oauth2
Flow: implicit
Authorization URL: https://login.microsoftonline.com/common/oauth2/authorize

Scopes

Name	Description
user_impersonation	impersonate your user account

Examples

CreateOrUpdateBudget

Sample request

HTTP

PUT https://management.azure.com/subscriptions/00000000-0000-0000-0000-000000000000/providers/Microsoft.Consumption/budgets/TestBudget?api-version=2024-08-01

{
  "eTag": "\"1d34d016a593709\"",
  "properties": {
    "amount": 100.65,
    "category": "Cost",
    "filter": {
      "and": [
        {
          "dimensions": {
            "name": "ResourceId",
            "operator": "In",
            "values": [
              "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/MYDEVTESTRG/providers/Microsoft.Compute/virtualMachines/MSVM2",
              "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/MYDEVTESTRG/providers/Microsoft.Compute/virtualMachines/platformcloudplatformGeneric1"
            ]
          }
        },
        {
          "tags": {
            "name": "category",
            "operator": "In",
            "values": [
              "Dev",
              "Prod"
            ]
          }
        },
        {
          "tags": {
            "name": "department",
            "operator": "In",
            "values": [
              "engineering",
              "sales"
            ]
          }
        }
      ]
    },
    "notifications": {
      "Actual_GreaterThan_80_Percent": {
        "contactEmails": [
          "johndoe@contoso.com",
          "janesmith@contoso.com"
        ],
        "contactGroups": [
          "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/MYDEVTESTRG/providers/microsoft.insights/actionGroups/SampleActionGroup"
        ],
        "contactRoles": [
          "Contributor",
          "Reader"
        ],
        "enabled": true,
        "locale": "en-us",
        "operator": "GreaterThan",
        "threshold": 80,
        "thresholdType": "Actual"
      }
    },
    "timeGrain": "Monthly",
    "timePeriod": {
      "endDate": "2018-10-31T00:00:00Z",
      "startDate": "2017-10-01T00:00:00Z"
    }
  }
}

Sample response

Status code:: 200

{
  "name": "TestBudget",
  "type": "Microsoft.Consumption/budgets",
  "eTag": "\"1d34d012214157f\"",
  "id": "subscriptions/00000000-0000-0000-0000-000000000000/providers/Microsoft.Consumption/budgets/TestBudget",
  "properties": {
    "amount": 100.65,
    "category": "Cost",
    "currentSpend": {
      "amount": 80.89,
      "unit": "USD"
    },
    "filter": {
      "and": [
        {
          "dimensions": {
            "name": "ResourceId",
            "operator": "In",
            "values": [
              "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/MYDEVTESTRG/providers/Microsoft.Compute/virtualMachines/MSVM2",
              "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/MYDEVTESTRG/providers/Microsoft.Compute/virtualMachines/platformcloudplatformGeneric1"
            ]
          }
        },
        {
          "tags": {
            "name": "category",
            "operator": "In",
            "values": [
              "Dev",
              "Prod"
            ]
          }
        },
        {
          "tags": {
            "name": "department",
            "operator": "In",
            "values": [
              "engineering",
              "sales"
            ]
          }
        }
      ]
    },
    "notifications": {
      "Actual_GreaterThan_80_Percent": {
        "contactEmails": [
          "johndoe@contoso.com",
          "janesmith@contoso.com"
        ],
        "contactGroups": [
          "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/MYDEVTESTRG/providers/microsoft.insights/actionGroups/SampleActionGroup"
        ],
        "contactRoles": [
          "Contributor",
          "Reader"
        ],
        "enabled": true,
        "locale": "en-us",
        "operator": "GreaterThan",
        "threshold": 80,
        "thresholdType": "Actual"
      }
    },
    "timeGrain": "Monthly",
    "timePeriod": {
      "endDate": "2018-10-31T00:00:00Z",
      "startDate": "2017-10-01T00:00:00Z"
    }
  }
}

Status code:: 201

{
  "name": "TestBudget",
  "type": "Microsoft.Consumption/budgets",
  "eTag": "\"1d34d012214157f\"",
  "id": "subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/MYDEVTESTRG/providers/Microsoft.Consumption/budgets/TestBudget",
  "properties": {
    "amount": 100.65,
    "category": "Cost",
    "currentSpend": {
      "amount": 80.89,
      "unit": "USD"
    },
    "filter": {
      "and": [
        {
          "dimensions": {
            "name": "ResourceId",
            "operator": "In",
            "values": [
              "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/MYDEVTESTRG/providers/Microsoft.Compute/virtualMachines/MSVM2",
              "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/MYDEVTESTRG/providers/Microsoft.Compute/virtualMachines/platformcloudplatformGeneric1"
            ]
          }
        },
        {
          "tags": {
            "name": "category",
            "operator": "In",
            "values": [
              "Dev",
              "Prod"
            ]
          }
        },
        {
          "tags": {
            "name": "department",
            "operator": "In",
            "values": [
              "engineering",
              "sales"
            ]
          }
        }
      ]
    },
    "notifications": {
      "Actual_GreaterThan_80_Percent": {
        "contactEmails": [
          "johndoe@contoso.com",
          "janesmith@contoso.com"
        ],
        "contactGroups": [
          "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/MYDEVTESTRG/providers/microsoft.insights/actionGroups/SampleActionGroup"
        ],
        "contactRoles": [
          "Contributor",
          "Reader"
        ],
        "enabled": true,
        "locale": "en-us",
        "operator": "GreaterThan",
        "threshold": 80,
        "thresholdType": "Actual"
      }
    },
    "timeGrain": "Monthly",
    "timePeriod": {
      "endDate": "2018-10-31T00:00:00Z",
      "startDate": "2017-10-01T00:00:00Z"
    }
  }
}

Definitions

Name	Description
Budget	A budget resource.
BudgetComparisonExpression	The comparison expression to be used in the budgets.
BudgetFilter	May be used to filter budgets by resource group, resource, or meter.
BudgetFilterProperties	The Dimensions or Tags to filter a budget by.
BudgetOperatorType	The operator to use for comparison.
BudgetTimePeriod	The start and end date for a budget.
CategoryType	The category of the budget, whether the budget tracks cost or usage.
createdByType	The type of identity that created the resource.
CultureCode	Language in which the recipient will receive the notification
CurrentSpend	The current amount of cost which is being tracked for a budget.
ErrorAdditionalInfo	The resource management error additional info.
ErrorDetail	The error detail.
ErrorResponse	Error response
ForecastSpend	The forecasted cost which is being tracked for a budget.
Notification	The notification associated with a budget.
OperatorType	The comparison operator.
systemData	Metadata pertaining to creation and last modification of the resource.
ThresholdType	The type of threshold
TimeGrainType	The time covered by a budget. Tracking of the amount will be reset based on the time grain. BillingMonth, BillingQuarter, and BillingAnnual are only supported by WD customers

Budget

Object

A budget resource.

Name	Type	Description
eTag	string	eTag of the resource. To handle concurrent update scenario, this field will be used to determine whether the user is updating the latest version or not.
id	string	Fully qualified resource ID for the resource. Ex - /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/{resourceProviderNamespace}/{resourceType}/{resourceName}
name	string	The name of the resource
properties.amount	number (decimal)	The total amount of cost to track with the budget
properties.category	CategoryType	The category of the budget, whether the budget tracks cost or usage.
properties.currentSpend	CurrentSpend	The current amount of cost which is being tracked for a budget.
properties.filter	BudgetFilter	May be used to filter budgets by user-specified dimensions and/or tags.
properties.forecastSpend	ForecastSpend	The forecasted cost which is being tracked for a budget.
properties.notifications	<string, Notification>	Dictionary of notifications associated with the budget. Budget can have up to five notifications.
properties.timeGrain	TimeGrainType	The time covered by a budget. Tracking of the amount will be reset based on the time grain. BillingMonth, BillingQuarter, and BillingAnnual are only supported by WD customers
properties.timePeriod	BudgetTimePeriod	Has start and end date of the budget. The start date must be first of the month and should be less than the end date. Budget start date must be on or after June 1, 2017. Future start date should not be more than twelve months. Past start date should be selected within the timegrain period. There are no restrictions on the end date.
systemData	systemData	Azure Resource Manager metadata containing createdBy and modifiedBy information.
type	string	The type of the resource. E.g. "Microsoft.Compute/virtualMachines" or "Microsoft.Storage/storageAccounts"

BudgetComparisonExpression

Object

The comparison expression to be used in the budgets.

Name	Type	Description
name	string	The name of the column to use in comparison.
operator	BudgetOperatorType	The operator to use for comparison.
values	string[]	Array of values to use for comparison

BudgetFilter

Object

May be used to filter budgets by resource group, resource, or meter.

Name	Type	Description
and	BudgetFilterProperties[]	The logical "AND" expression. Must have at least 2 items.
dimensions	BudgetComparisonExpression	Has comparison expression for a dimension
tags	BudgetComparisonExpression	Has comparison expression for a tag

BudgetFilterProperties

Object

The Dimensions or Tags to filter a budget by.

Name	Type	Description
dimensions	BudgetComparisonExpression	Has comparison expression for a dimension
tags	BudgetComparisonExpression	Has comparison expression for a tag

BudgetOperatorType

Enumeration

The operator to use for comparison.

Value	Description
In

BudgetTimePeriod

Object

The start and end date for a budget.

Name	Type	Description
endDate	string (date-time)	The end date for the budget. If not provided, we default this to 10 years from the start date.
startDate	string (date-time)	The start date for the budget.

CategoryType

Enumeration

The category of the budget, whether the budget tracks cost or usage.

Value	Description
Cost

createdByType

Enumeration

The type of identity that created the resource.

Value	Description
User
Application
ManagedIdentity
Key

CultureCode

Enumeration

Language in which the recipient will receive the notification

Value	Description
en-us
ja-jp
zh-cn
de-de
es-es
fr-fr
it-it
ko-kr
pt-br
ru-ru
zh-tw
cs-cz
pl-pl
tr-tr
da-dk
en-gb
hu-hu
nb-no
nl-nl
pt-pt
sv-se

CurrentSpend

Object

The current amount of cost which is being tracked for a budget.

Name	Type	Description
amount	number (decimal)	The total amount of cost which is being tracked by the budget.
unit	string	The unit of measure for the budget amount.

ErrorAdditionalInfo

Object

The resource management error additional info.

Name	Type	Description
info	object	The additional info.
type	string	The additional info type.

ErrorDetail

Object

The error detail.

Name	Type	Description
additionalInfo	ErrorAdditionalInfo[]	The error additional info.
code	string	The error code.
details	ErrorDetail[]	The error details.
message	string	The error message.
target	string	The error target.

ErrorResponse

Object

Error response

Name	Type	Description
error	ErrorDetail	The error object.

ForecastSpend

Object

The forecasted cost which is being tracked for a budget.

Name	Type	Description
amount	number (decimal)	The forecasted cost for the total time period which is being tracked by the budget. This value is only provided if the budget contains a forecast alert type.
unit	string	The unit of measure for the budget amount.

Notification

Object

The notification associated with a budget.

Name	Type	Default value	Description
contactEmails	string[]		Email addresses to send the budget notification to when the threshold is exceeded. Must have at least one contact email or contact group specified at the Subscription or Resource Group scopes. All other scopes must have at least one contact email specified.
contactGroups	string[]		Action groups to send the budget notification to when the threshold is exceeded. Must be provided as a fully qualified Azure resource id. Only supported at Subscription or Resource Group scopes.
contactRoles	string[]		Contact roles to send the budget notification to when the threshold is exceeded.
enabled	boolean		The notification is enabled or not.
locale	CultureCode		Language in which the recipient will receive the notification
operator	OperatorType		The comparison operator.
threshold	number (decimal)		Threshold value associated with a notification. Notification is sent when the cost exceeded the threshold. It is always percent and has to be between 0 and 1000.
thresholdType	ThresholdType	Actual	The type of threshold

OperatorType

Enumeration

The comparison operator.

Value	Description
EqualTo	Alert will be triggered if the evaluated cost is the same as threshold value. Note: It’s not recommended to use this OperatorType as there’s low chance of cost being exactly the same as threshold value, leading to missing of your alert. This OperatorType will be deprecated in future.
GreaterThan	Alert will be triggered if the evaluated cost is greater than the threshold value. Note: This is the recommended OperatorType while configuring Budget Alert.
GreaterThanOrEqualTo	Alert will be triggered if the evaluated cost is greater than or equal to the threshold value.

systemData

Object

Metadata pertaining to creation and last modification of the resource.

Name	Type	Description
createdAt	string (date-time)	The timestamp of resource creation (UTC).
createdBy	string	The identity that created the resource.
createdByType	createdByType	The type of identity that created the resource.
lastModifiedAt	string (date-time)	The timestamp of resource last modification (UTC)
lastModifiedBy	string	The identity that last modified the resource.
lastModifiedByType	createdByType	The type of identity that last modified the resource.

ThresholdType

Enumeration

The type of threshold

Value	Description
Actual	Actual costs budget alerts notify when the actual accrued cost exceeds the allocated budget .
Forecasted	Forecasted costs budget alerts provide advanced notification that your spending trends are likely to exceed your allocated budget, as it relies on forecasted cost predictions.

TimeGrainType

Enumeration

The time covered by a budget. Tracking of the amount will be reset based on the time grain. BillingMonth, BillingQuarter, and BillingAnnual are only supported by WD customers

Value	Description
Monthly
Quarterly
Annually
BillingMonth
BillingQuarter
BillingAnnual

Share via

Budgets - Create Or Update

URI Parameters

Request Body

Responses

Security

azure_auth

Scopes

Examples

CreateOrUpdateBudget

Sample request

Sample response

Definitions

Budget

BudgetComparisonExpression

BudgetFilter

BudgetFilterProperties

BudgetOperatorType

BudgetTimePeriod

CategoryType

createdByType

CultureCode

CurrentSpend

ErrorAdditionalInfo

ErrorDetail

ErrorResponse

ForecastSpend

Notification

OperatorType

systemData

ThresholdType

TimeGrainType