CreateBillEstimate - AWS Billing and Cost Management

CreateBillEstimate

Create a Bill estimate from a Bill scenario. In the Bill scenario you can model usage addition, usage changes, and usage removal. You can also model commitment addition and commitment removal. After all changes in a Bill scenario is made satisfactorily, you can call this API with a Bill scenario ID to generate the Bill estimate. Bill estimate calculates the pre-tax cost for your consolidated billing family, incorporating all modeled usage and commitments alongside existing usage and commitments from your most recent completed anniversary bill, with any applicable discounts applied.

Request Syntax

{ "billScenarioId": "string", "clientToken": "string", "name": "string", "tags": { "string" : "string" } }

Request Parameters

For information about the parameters that are common to all actions, see Common Parameters.

The request accepts the following data in JSON format.

billScenarioId

The ID of the Bill Scenario for which you want to create a Bill estimate.

Type: String

Length Constraints: Fixed length of 36.

Pattern: [a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}

Required: Yes

clientToken

A unique, case-sensitive identifier that you provide to ensure the idempotency of the request.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 64.

Pattern: [\u0021-\u007E]+

Required: No

name

The name of the Bill estimate that will be created. Names must be unique for an account.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 64.

Pattern: [a-zA-Z0-9-]+

Required: Yes

tags

An optional list of tags to associate with the specified BillEstimate. You can use resource tags to control access to your BillEstimate using IAM policies. Each tag consists of a key and a value, and each key must be unique for the resource. The following restrictions apply to resource tags:

  • Although the maximum number of array members is 200, you can assign a maximum of 50 user-tags to one resource. The remaining are reserved for AWS.

  • The maximum length of a key is 128 characters.

  • The maximum length of a value is 256 characters.

  • Keys and values can only contain alphanumeric characters, spaces, and any of the following: _.:/=+@-.

  • Keys and values are case sensitive.

  • Keys and values are trimmed for any leading or trailing whitespaces.

  • Don't use aws: as a prefix for your keys. This prefix is reserved for AWS.

Type: String to string map

Map Entries: Minimum number of 0 items. Maximum number of 200 items.

Key Length Constraints: Minimum length of 1. Maximum length of 128.

Key Pattern: [\w\s:+=@/-]+

Value Length Constraints: Minimum length of 0. Maximum length of 256.

Value Pattern: [\w\s:+=@/-]*

Required: No

Response Syntax

{ "billInterval": { "end": number, "start": number }, "costSummary": { "serviceCostDifferences": { "string" : { "estimatedCost": { "amount": number, "currency": "string" }, "historicalCost": { "amount": number, "currency": "string" } } }, "totalCostDifference": { "estimatedCost": { "amount": number, "currency": "string" }, "historicalCost": { "amount": number, "currency": "string" } } }, "createdAt": number, "expiresAt": number, "failureMessage": "string", "id": "string", "name": "string", "status": "string" }

Response Elements

If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

billInterval

The bill month start and end timestamp that was used to create the Bill estimate. This is set to the last complete anniversary bill month start and end timestamp.

Type: BillInterval object

costSummary

Returns summary-level cost information once a Bill estimate is successfully generated. This summary includes: 1) the total cost difference, showing the pre-tax cost change for the consolidated billing family between the completed anniversary bill and the estimated bill, and 2) total cost differences per service, detailing the pre-tax cost of each service, comparing the completed anniversary bill to the estimated bill on a per-service basis.

Type: BillEstimateCostSummary object

createdAt

The timestamp of when the Bill estimate create process was started (not when it successfully completed or failed).

Type: Timestamp

expiresAt

The timestamp of when the Bill estimate will expire. A Bill estimate becomes inaccessible after expiration.

Type: Timestamp

failureMessage

This attribute provides the reason if a Bill estimate result generation fails.

Type: String

id

The unique identifier of your newly created Bill estimate.

Type: String

Length Constraints: Fixed length of 36.

Pattern: [a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}

name

The name of your newly created Bill estimate.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 64.

Pattern: [a-zA-Z0-9-]+

status

The status of your newly created Bill estimate. Bill estimate creation can take anywhere between 8 to 12 hours. The status will allow you to identify when the Bill estimate is complete or has failed.

Type: String

Valid Values: IN_PROGRESS | COMPLETE | FAILED

Errors

For information about the errors that are common to all actions, see Common Errors.

AccessDeniedException

You do not have sufficient access to perform this action.

HTTP Status Code: 400

ConflictException

The request could not be processed because of conflict in the current state of the resource.

HTTP Status Code: 400

DataUnavailableException

The requested data is currently unavailable.

HTTP Status Code: 400

InternalServerException

An internal error has occurred. Retry your request, but if the problem persists, contact AWS support.

HTTP Status Code: 500

ResourceNotFoundException

The specified resource was not found.

HTTP Status Code: 400

ThrottlingException

The request was denied due to request throttling.

HTTP Status Code: 400

ValidationException

The input provided fails to satisfy the constraints specified by an AWS service.

HTTP Status Code: 400

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the following: