Share via

Cost Allocation Rules - Create Or Update

Service:
Cost Management
API Version:
2025-03-01

Create/Update a rule to allocate cost between different resources within a billing account or enterprise enrollment.

PUT https://management.azure.com/providers/Microsoft.Billing/billingAccounts/{billingAccountId}/providers/Microsoft.CostManagement/costAllocationRules/{ruleName}?api-version=2025-03-01

URI Parameters

Name In Required Type Description
billingAccountId
 path True

string

BillingAccount ID
ruleName
 path True

string

pattern: [A-Za-z0-9\-_]+

Cost allocation rule name. The name cannot include spaces or any non alphanumeric characters other than '_' and '-'. The max length is 260 characters.
api-version
 query True

string

minLength: 1

The API version to use for this operation.

Request Body

Name Type Description
properties

CostAllocationRuleProperties

Cost allocation rule properties

Responses

Name Type Description
200 OK

CostAllocationRuleDefinition

OK. The update request has succeeded.
201 Created

CostAllocationRuleDefinition

Created. The request has succeeded.
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

CostAllocationRulesCreateResourceGroup
CostAllocationRulesCreateTag

CostAllocationRulesCreateResourceGroup

Sample request

PUT https://management.azure.com/providers/Microsoft.Billing/billingAccounts/100/providers/Microsoft.CostManagement/costAllocationRules/testRule?api-version=2025-03-01

{
  "properties": {
    "description": "This is a testRule",
    "status": "Active",
    "details": {
      "sourceResources": [
        {
          "resourceType": "Dimension",
          "name": "ResourceGroupName",
          "values": [
            "sampleRG",
            "secondRG"
          ]
        }
      ],
      "targetResources": [
        {
          "resourceType": "Dimension",
          "policyType": "FixedProportion",
          "name": "ResourceGroupName",
          "values": [
            {
              "name": "destinationRG",
              "percentage": 45
            },
            {
              "name": "destinationRG2",
              "percentage": 54
            }
          ]
        }
      ]
    }
  }
}

Sample response

Status code:
200 
{
  "id": "providers/Microsoft.Billing/billingAccounts/100/providers/Microsoft.CostManagement/costAllocationRules/testRule",
  "name": "testRule",
  "type": "Microsoft.CostManagement/costAllocationRules",
  "properties": {
    "description": "This is a testRule",
    "createdDate": "2020-06-18T22:21:51.1287144Z",
    "updatedDate": "2020-06-18T22:21:51.1287144Z",
    "status": "Creating",
    "details": {
      "sourceResources": [
        {
          "resourceType": "Dimension",
          "name": "ResourceGroupName",
          "values": [
            "sampleRG"
          ]
        }
      ],
      "targetResources": [
        {
          "resourceType": "Dimension",
          "policyType": "FixedProportion",
          "name": "ResourceGroupName",
          "values": [
            {
              "name": "destinationRG",
              "percentage": 50
            },
            {
              "name": "destinationRG2",
              "percentage": 50
            }
          ]
        }
      ]
    }
  }
}
Status code:
201 
{
  "id": "providers/Microsoft.Billing/billingAccounts/100/providers/Microsoft.CostManagement/costAllocationRules/testRule",
  "name": "testRule",
  "type": "Microsoft.CostManagement/costAllocationRules",
  "properties": {
    "description": "This is a testRule",
    "createdDate": "2020-06-18T22:21:51.1287144Z",
    "updatedDate": "2020-06-18T22:21:51.1287144Z",
    "status": "Creating",
    "details": {
      "sourceResources": [
        {
          "resourceType": "Dimension",
          "name": "ResourceGroupName",
          "values": [
            "sampleRG"
          ]
        }
      ],
      "targetResources": [
        {
          "resourceType": "Dimension",
          "policyType": "FixedProportion",
          "name": "ResourceGroupName",
          "values": [
            {
              "name": "destinationRG",
              "percentage": 50
            },
            {
              "name": "destinationRG2",
              "percentage": 50
            }
          ]
        }
      ]
    }
  }
}

CostAllocationRulesCreateTag

Sample request

PUT https://management.azure.com/providers/Microsoft.Billing/billingAccounts/100/providers/Microsoft.CostManagement/costAllocationRules/testRule?api-version=2025-03-01

{
  "properties": {
    "description": "This is a testRule",
    "status": "Active",
    "details": {
      "sourceResources": [
        {
          "resourceType": "Tag",
          "name": "category",
          "values": [
            "devops"
          ]
        }
      ],
      "targetResources": [
        {
          "resourceType": "Dimension",
          "policyType": "FixedProportion",
          "name": "ResourceGroupName",
          "values": [
            {
              "name": "destinationRG",
              "percentage": 33.33
            },
            {
              "name": "destinationRG2",
              "percentage": 33.33
            },
            {
              "name": "destinationRG3",
              "percentage": 33.34
            }
          ]
        }
      ]
    }
  }
}

Sample response

Status code:
200 
{
  "id": "providers/Microsoft.Billing/billingAccounts/100/providers/Microsoft.CostManagement/costAllocationRules/testRule",
  "name": "testRule",
  "type": "Microsoft.CostManagement/costAllocationRules",
  "properties": {
    "description": "This is a testRule",
    "createdDate": "2020-06-18T22:21:51.1287144Z",
    "updatedDate": "2020-06-18T22:21:51.1287144Z",
    "status": "Creating",
    "details": {
      "sourceResources": [
        {
          "resourceType": "Dimension",
          "name": "ResourceGroupName",
          "values": [
            "sampleRG"
          ]
        }
      ],
      "targetResources": [
        {
          "resourceType": "Dimension",
          "policyType": "FixedProportion",
          "name": "ResourceGroupName",
          "values": [
            {
              "name": "destinationRG",
              "percentage": 50
            },
            {
              "name": "destinationRG2",
              "percentage": 50
            }
          ]
        }
      ]
    }
  }
}
Status code:
201 
{
  "id": "providers/Microsoft.Billing/billingAccounts/100/providers/Microsoft.CostManagement/costAllocationRules/testRule",
  "name": "testRule",
  "type": "Microsoft.CostManagement/costAllocationRules",
  "properties": {
    "description": "This is a testRule",
    "createdDate": "2020-06-18T22:21:51.1287144Z",
    "updatedDate": "2020-06-18T22:21:51.1287144Z",
    "status": "Creating",
    "details": {
      "sourceResources": [
        {
          "resourceType": "Dimension",
          "name": "ResourceGroupName",
          "values": [
            "sampleRG"
          ]
        }
      ],
      "targetResources": [
        {
          "resourceType": "Dimension",
          "policyType": "FixedProportion",
          "name": "ResourceGroupName",
          "values": [
            {
              "name": "destinationRG",
              "percentage": 50
            },
            {
              "name": "destinationRG2",
              "percentage": 50
            }
          ]
        }
      ]
    }
  }
}

Definitions

Name Description
CostAllocationPolicyType

Method to use for allocating cost. FixedProportion indicates that cost will be split based on specified percentage values.
CostAllocationProportion

Target resources and allocation
CostAllocationResourceType

Category of resource to use for allocation.
CostAllocationRuleDefinition

The cost allocation rule model definition
CostAllocationRuleDetails

Resource details of the cost allocation rule
CostAllocationRuleProperties

The properties of a cost allocation rule
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.
RuleStatus

Current status of the rule.
SourceCostAllocationResource

Source resources for cost allocation
TargetCostAllocationResource

Target resources for cost allocation.

CostAllocationPolicyType

Enumeration

Method to use for allocating cost. FixedProportion indicates that cost will be split based on specified percentage values.

Value Description
FixedProportion

CostAllocationProportion

Object

Target resources and allocation

Name Type Description
name

string

Target resource for cost allocation
percentage

number

Percentage of source cost to allocate to this resource. This value can be specified to two decimal places and the total percentage of all resources in this rule must sum to 100.00.

CostAllocationResourceType

Enumeration

Category of resource to use for allocation.

Value Description
Dimension

Indicates an Azure dimension such as a subscription id or resource group name is being used for allocation.
Tag

Allocates cost based on Azure Tag key value pairs.

CostAllocationRuleDefinition

Object

The cost allocation rule model definition

Name Type Description
id

string

Azure Resource Manager Id for the rule. This is a read ony value.
name

string

Name of the rule. This is a read only value.
properties

CostAllocationRuleProperties

Cost allocation rule properties
type

string

Resource type of the rule. This is a read only value of Microsoft.CostManagement/CostAllocationRule.

CostAllocationRuleDetails

Object

Resource details of the cost allocation rule

Name Type Description
sourceResources

SourceCostAllocationResource[]

Source resources for cost allocation. At this time, this list can contain no more than one element.
targetResources

TargetCostAllocationResource[]

Target resources for cost allocation. At this time, this list can contain no more than one element.

CostAllocationRuleProperties

Object

The properties of a cost allocation rule

Name Type Description
createdDate

string (date-time)

Time at which the rule was created. Rules that change cost for the same resource are applied in order of creation.
description

string

Description of a cost allocation rule.
details

CostAllocationRuleDetails

Resource information for the cost allocation rule
status

RuleStatus

Status of the rule
updatedDate

string (date-time)

Time at which the rule was last updated.

ErrorDetails

Object

The details of the error.

Name Type Description
code

string

Error code.
message

string

Error message indicating why the operation failed.

ErrorResponse

Object

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.

Name Type Description
error

ErrorDetails

The details of the error.

RuleStatus

Enumeration

Current status of the rule.

Value Description
NotActive

Rule is saved but not used to allocate costs.
Active

Rule is saved and impacting cost allocation.
Processing

Rule is saved and cost allocation is being updated. Readonly value that cannot be submitted in a put request.

SourceCostAllocationResource

Object

Source resources for cost allocation

Name Type Description
name

string

If resource type is dimension, this must be either ResourceGroupName or SubscriptionId. If resource type is tag, this must be a valid Azure tag
resourceType

CostAllocationResourceType

Type of resources contained in this cost allocation rule
values

string[]

Source Resources for cost allocation. This list cannot contain more than 25 values.

TargetCostAllocationResource

Object

Target resources for cost allocation.

Name Type Description
name

string

If resource type is dimension, this must be either ResourceGroupName or SubscriptionId. If resource type is tag, this must be a valid Azure tag
policyType

CostAllocationPolicyType

Method of cost allocation for the rule
resourceType

CostAllocationResourceType

Type of resources contained in this cost allocation rule
values

CostAllocationProportion[]

Target resources for cost allocation. This list cannot contain more than 25 values.