Share via

Budgets - Create Or Update

  • Reference
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 scope associated with budget operations. This includes '/subscriptions/{subscriptionId}/' for subscription scope, '/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}' for resourceGroup scope, '/providers/Microsoft.Billing/billingAccounts/{billingAccountId}' for Billing Account scope, '/providers/Microsoft.Billing/billingAccounts/{billingAccountId}/departments/{departmentId}' for Department scope, '/providers/Microsoft.Billing/billingAccounts/{billingAccountId}/enrollmentAccounts/{enrollmentAccountId}' for EnrollmentAccount scope, '/providers/Microsoft.Management/managementGroups/{managementGroupId}' for Management Group scope, '/providers/Microsoft.Billing/billingAccounts/{billingAccountId}/billingProfiles/{billingProfileId}' for billingProfile scope, '/providers/Microsoft.Billing/billingAccounts/{billingAccountId}/invoiceSections/{invoiceSectionId}' for invoiceSection scope.
api-version
 query True

string

Version of the API to be used with the client request. The current version is 2023-03-01.

Request Body

Name Required Type Description
properties.amount True

number

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

OK. The request has succeeded.
201 Created

Budget

Created.
Other Status Codes

ErrorResponse

Error response describing why the operation failed.

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

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

{
  "eTag": "\"1d34d016a593709\"",
  "properties": {
    "category": "Cost",
    "amount": 100.65,
    "timeGrain": "Monthly",
    "timePeriod": {
      "startDate": "2017-10-01T00:00:00Z",
      "endDate": "2018-10-31T00:00:00Z"
    },
    "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": {
        "enabled": true,
        "operator": "GreaterThan",
        "threshold": 80,
        "locale": "en-us",
        "contactEmails": [
          "johndoe@contoso.com",
          "janesmith@contoso.com"
        ],
        "contactRoles": [
          "Contributor",
          "Reader"
        ],
        "contactGroups": [
          "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/MYDEVTESTRG/providers/microsoft.insights/actionGroups/SampleActionGroup"
        ],
        "thresholdType": "Actual"
      }
    }
  }
}

Sample response

Status code:
201 
{
  "id": "subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/MYDEVTESTRG/providers/Microsoft.Consumption/budgets/TestBudget",
  "name": "TestBudget",
  "type": "Microsoft.Consumption/budgets",
  "eTag": "\"1d34d012214157f\"",
  "properties": {
    "category": "Cost",
    "amount": 100.65,
    "timeGrain": "Monthly",
    "timePeriod": {
      "startDate": "2017-10-01T00:00:00Z",
      "endDate": "2018-10-31T00:00:00Z"
    },
    "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"
            ]
          }
        }
      ]
    },
    "currentSpend": {
      "amount": 80.89,
      "unit": "USD"
    },
    "notifications": {
      "Actual_GreaterThan_80_Percent": {
        "enabled": true,
        "operator": "GreaterThan",
        "threshold": 80,
        "locale": "en-us",
        "contactEmails": [
          "johndoe@contoso.com",
          "janesmith@contoso.com"
        ],
        "contactRoles": [
          "Contributor",
          "Reader"
        ],
        "contactGroups": [
          "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/MYDEVTESTRG/providers/microsoft.insights/actionGroups/SampleActionGroup"
        ],
        "thresholdType": "Actual"
      }
    }
  }
}
Status code:
200 
{
  "id": "subscriptions/00000000-0000-0000-0000-000000000000/providers/Microsoft.Consumption/budgets/TestBudget",
  "name": "TestBudget",
  "type": "Microsoft.Consumption/budgets",
  "eTag": "\"1d34d012214157f\"",
  "properties": {
    "category": "Cost",
    "amount": 100.65,
    "timeGrain": "Monthly",
    "timePeriod": {
      "startDate": "2017-10-01T00:00:00Z",
      "endDate": "2018-10-31T00:00:00Z"
    },
    "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"
            ]
          }
        }
      ]
    },
    "currentSpend": {
      "amount": 80.89,
      "unit": "USD"
    },
    "notifications": {
      "Actual_GreaterThan_80_Percent": {
        "enabled": true,
        "operator": "GreaterThan",
        "threshold": 80,
        "locale": "en-us",
        "contactEmails": [
          "johndoe@contoso.com",
          "janesmith@contoso.com"
        ],
        "contactRoles": [
          "Contributor",
          "Reader"
        ],
        "contactGroups": [
          "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/MYDEVTESTRG/providers/microsoft.insights/actionGroups/SampleActionGroup"
        ],
        "thresholdType": "Actual"
      }
    }
  }
}

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.
CultureCode

Language in which the recipient will receive the notification
CurrentSpend

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

The details of the error.
ErrorResponse

Error response indicates that the service is not able to process the incoming request. The reason is provided in the error message.

Some Error responses:

  • 429 TooManyRequests - Request is throttled. Retry after waiting for the time specified in the "x-ms-ratelimit-microsoft.consumption-retry-after" header.

  • 503 ServiceUnavailable - Service is temporarily unavailable. Retry after waiting for the time specified in the "Retry-After" header.

  • 504 Gateway Timeout - Service timed out while processing the request. Reduce the date range in the request, if possible.
ForecastSpend

The forecasted cost which is being tracked for a budget.
Notification

The notification associated with a budget.
OperatorType

The comparison operator.
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

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

Resource Id.
name

string

Resource name.
properties.amount

number

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.
type

string

Resource type.

BudgetComparisonExpression

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

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

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

The operator to use for comparison.

Name Type Description
In

string

BudgetTimePeriod

The start and end date for a budget.

Name Type Description
endDate

string

The end date for the budget. If not provided, we default this to 10 years from the start date.
startDate

string

The start date for the budget.

CategoryType

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

Name Type Description
Cost

string

CultureCode

Language in which the recipient will receive the notification

Name Type Description
cs-cz

string

da-dk

string

de-de

string

en-gb

string

en-us

string

es-es

string

fr-fr

string

hu-hu

string

it-it

string

ja-jp

string

ko-kr

string

nb-no

string

nl-nl

string

pl-pl

string

pt-br

string

pt-pt

string

ru-ru

string

sv-se

string

tr-tr

string

zh-cn

string

zh-tw

string

CurrentSpend

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

Name Type Description
amount

number

The total amount of cost which is being tracked by the budget.
unit

string

The unit of measure for the budget amount.

ErrorDetails

The details of the error.

Name Type Description
code

string

Error code.
message

string

Error message indicating why the operation failed.

ErrorResponse

Error response indicates that the service is not able to process the incoming request. The reason is provided in the error message.

Some Error responses:

  • 429 TooManyRequests - Request is throttled. Retry after waiting for the time specified in the "x-ms-ratelimit-microsoft.consumption-retry-after" header.

  • 503 ServiceUnavailable - Service is temporarily unavailable. Retry after waiting for the time specified in the "Retry-After" header.

  • 504 Gateway Timeout - Service timed out while processing the request. Reduce the date range in the request, if possible.

Name Type Description
error

ErrorDetails

The details of the error.

ForecastSpend

The forecasted cost which is being tracked for a budget.

Name Type Description
amount

number

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

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

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

The comparison operator.

Name Type Description
EqualTo

string

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

string

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

string

Alert will be triggered if the evaluated cost is greater than or equal to the threshold value.

ThresholdType

The type of threshold

Name Type Description
Actual

string

Actual costs budget alerts notify when the actual accrued cost exceeds the allocated budget .
Forecasted

string

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

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

Name Type Description
Annually

string

BillingAnnual

string

BillingMonth

string

BillingQuarter

string

Monthly

string

Quarterly

string