2026/07/06 - AWS Billing - 5 new api methods
Changes Adds support for managing AWS account credits and billing preferences, including retrieving credit details, viewing per-month credit allocation history, redeeming promotional codes, and configuring credit sharing and billing preferences.
Redeems an Amazon Web Services promotional credit code on behalf of the calling account. On success, a new credit is added to the account's credit ledger with the amount, validity period, and applicable products defined by the promotion. The credit is then automatically applied to subsequent bills according to the standard credit application order.
See also: AWS API Documentation
Request Syntax
client.redeem_credits(
promoCode='string'
)
string
[REQUIRED]
The promotional credit code to redeem.
dict
Response Syntax
{}
Response Structure
(dict) --
Returns the list of Amazon Web Services account credits for the specified account. Each credit includes its identifier, type, monetary amounts, applicable products, expiration, sharing configuration, and current enabled status.
When the caller is the management account of a consolidated billing family and payerAccountFlag is true, the response aggregates credits across the entire family. Otherwise, the response includes only credits owned by the account specified in accountId.
See also: AWS API Documentation
Request Syntax
client.get_credits(
accountId='string',
startDate=datetime(2015, 1, 1),
endDate=datetime(2015, 1, 1),
payerAccountFlag=True|False
)
string
[REQUIRED]
The Amazon Web Services account ID. Must be a 12-digit numeric string.
datetime
[REQUIRED]
The start date for the credit period as Unix epoch seconds. Must be a past date that is not more than one year before the current date.
datetime
The end date for the credit period as Unix epoch seconds. Must not be a future date and must be on or after startDate. Defaults to the current date when omitted.
boolean
When true and the caller is the management account, the response aggregates credits across the entire consolidated billing family. When false or omitted, returns only credits for the specified accountId.
dict
Response Syntax
{
'credits': [
{
'creditId': 'string',
'accountId': 'string',
'creditType': 'string',
'initialAmount': {
'currencyCode': 'string',
'currencyAmount': 'string'
},
'remainingAmount': {
'currencyCode': 'string',
'currencyAmount': 'string'
},
'estimatedAmount': {
'currencyCode': 'string',
'currencyAmount': 'string'
},
'applicableProductNames': [
'string',
],
'description': 'string',
'startDate': datetime(2015, 1, 1),
'endDate': datetime(2015, 1, 1),
'exhaustDate': datetime(2015, 1, 1),
'applicationType': 'BEFORE_CROSS_SERVICE_DISCOUNTS'|'AFTER_DISCOUNTS',
'shareableAccounts': [
'string',
],
'accountHasCreditSharingEnabled': True|False,
'creditConsoleVisibility': 'string',
'creditSharingType': 'DEFAULT'|'DISABLED'|'CUSTOM'|'COST_CATEGORY_RULE',
'costCategoryArn': 'string',
'ruleName': 'string',
'creditStatus': 'ENABLED'|'DISABLED',
'purchaseTypeApplications': [
'string',
]
},
]
}
Response Structure
(dict) --
credits (list) --
The list of credits matching the request. Returns an empty list when no credits exist.
(dict) --
Detailed information about an Amazon Web Services credit, including its identifier, type, monetary amounts, applicable products, sharing configuration, and current enabled status.
creditId (string) --
The unique identifier for the credit.
accountId (string) --
The Amazon Web Services account ID that owns the credit.
creditType (string) --
The type of credit. Examples: Promotion, Refund, TrueUp.
initialAmount (dict) --
The initial amount of the credit when it was issued.
currencyCode (string) --
The ISO 4217 currency code for the amount (for example, USD).
currencyAmount (string) --
The amount as a decimal string (for example, "743.21"). Negative values represent credits that reduce a bill.
remainingAmount (dict) --
The unused balance of the credit.
currencyCode (string) --
The ISO 4217 currency code for the amount (for example, USD).
currencyAmount (string) --
The amount as a decimal string (for example, "743.21"). Negative values represent credits that reduce a bill.
estimatedAmount (dict) --
The estimated remaining balance, including in-flight (open) bills that have not yet been finalized.
currencyCode (string) --
The ISO 4217 currency code for the amount (for example, USD).
currencyAmount (string) --
The amount as a decimal string (for example, "743.21"). Negative values represent credits that reduce a bill.
applicableProductNames (list) --
The names of Amazon Web Services services this credit applies to.
(string) --
description (string) --
A human-readable description of the credit.
startDate (datetime) --
The date the credit becomes valid, as Unix epoch seconds.
endDate (datetime) --
The date the credit expires, as Unix epoch seconds.
exhaustDate (datetime) --
The date the credit balance reached zero, as Unix epoch seconds.
applicationType (string) --
When the credit is applied during bill computation. Valid values: BEFORE_CROSS_SERVICE_DISCOUNTS, AFTER_DISCOUNTS.
shareableAccounts (list) --
The Amazon Web Services account IDs entitled to apply this credit.
(string) --
accountHasCreditSharingEnabled (boolean) --
Whether the owning account has account-level credit sharing turned on.
creditConsoleVisibility (string) --
The display configuration for the credit in the Amazon Web Services Billing console.
creditSharingType (string) --
The sharing configuration for the credit. Valid values: DEFAULT, DISABLED, CUSTOM, COST_CATEGORY_RULE.
costCategoryArn (string) --
The Amazon Resource Name (ARN) of the Cost Category controlling the credit's sharing scope. Present only when creditSharingType is COST_CATEGORY_RULE.
ruleName (string) --
The rule name within the Cost Category. Present only when creditSharingType is COST_CATEGORY_RULE.
creditStatus (string) --
Whether the credit participates in billing runs. Valid values: ENABLED, DISABLED.
purchaseTypeApplications (list) --
Restricts which purchase types this credit applies to. When null or omitted, the credit applies to all purchase types.
(string) --
Retrieves billing preferences for the specified feature. Each feature controls a distinct billing capability: which accounts can share Reserved Instances or credits, whether billing alerts are enabled, the historical record of sharing changes, and per-credit options.
See also: AWS API Documentation
Request Syntax
client.get_billing_preferences(
nextToken='string',
maxResults=123,
features=[
'RI_SHARING'|'RI_SHARING_HISTORY'|'CREDIT_SHARING'|'CREDIT_SHARING_HISTORY'|'CREDIT_LEVEL_SHARING'|'BILLING_ALERTS'|'CREDIT_PREFERENCE_OPTIONS',
],
filters=[
{
'name': 'PREFERENCE_KEY',
'value': [
'string',
]
},
]
)
string
Pagination token from a previous response. Pass the value returned in nextToken to retrieve the next page of results.
integer
The maximum number of records to return per page. Range: 1 to 50. Default: 50.
list
[REQUIRED]
The feature to retrieve. Specify exactly one value. Valid values: BILLING_ALERTS, RI_SHARING, RI_SHARING_HISTORY, CREDIT_SHARING, CREDIT_SHARING_HISTORY, CREDIT_LEVEL_SHARING, CREDIT_PREFERENCE_OPTIONS.
(string) --
list
Filters to narrow results. Specify exactly one filter when supplied. The supported filter name is PREFERENCE_KEY, which accepts 1 to 10 values to match preference keys.
(dict) --
A filter that narrows the set of preferences returned by GetBillingPreferences.
name (string) --
The filter name. Currently the only supported value is PREFERENCE_KEY.
value (list) --
The filter values to match. For PREFERENCE_KEY, supply 1 to 10 preference key values to match.
(string) --
dict
Response Syntax
{
'billingPreferences': [
{
'feature': 'RI_SHARING'|'RI_SHARING_HISTORY'|'CREDIT_SHARING'|'CREDIT_SHARING_HISTORY'|'CREDIT_LEVEL_SHARING'|'BILLING_ALERTS'|'CREDIT_PREFERENCE_OPTIONS',
'key': 'string',
'value': 'ENABLED'|'DISABLED',
'accountName': 'string',
'accountId': 'string',
'billingPeriod': {
'year': 123,
'month': 123
}
},
],
'nextToken': 'string'
}
Response Structure
(dict) --
billingPreferences (list) --
The list of preference entries matching the request.
(dict) --
A single billing preference entry returned by GetBillingPreferences.
feature (string) --
The feature this preference belongs to.
key (string) --
The preference key. Format depends on the feature.
value (string) --
The preference value. Valid values: ENABLED or DISABLED.
accountName (string) --
The display name of the account. Populated together with accountId; null otherwise.
accountId (string) --
The associated Amazon Web Services account ID. Populated for account-list keys; null otherwise.
billingPeriod (dict) --
The billing period associated with the preference change. Populated only for the history features RI_SHARING_HISTORY and CREDIT_SHARING_HISTORY.
year (integer) --
The four-digit year of the billing period.
month (integer) --
The month of the billing period as an integer between 1 and 12.
nextToken (string) --
Pagination token. Present when more pages are available; null when there are no more results.
Returns the per-billing-month allocation history for credits applied to an Amazon Web Services account's bills. Traverses the consolidated billing family to capture cross-account credit applications. Supports pagination and optional filtering to a single credit.
See also: AWS API Documentation
Request Syntax
client.get_credit_allocation_history(
accountId='string',
creditId=123,
startDate=datetime(2015, 1, 1),
endDate=datetime(2015, 1, 1),
nextToken='string',
maxResults=123
)
string
[REQUIRED]
The Amazon Web Services account ID whose allocation history to retrieve. Must be a 12-digit numeric string.
integer
Filters the result to a single credit. When omitted, returns allocation entries for all credits.
datetime
[REQUIRED]
Inclusive start date as Unix epoch seconds. Must be on or before endDate. The range from startDate to endDate cannot exceed 24 billing months.
datetime
[REQUIRED]
Inclusive end date as Unix epoch seconds.
string
Pagination token from a previous response. Pass the value returned in nextToken to retrieve the next page of results.
integer
The maximum number of records to return per page. Range: 1 to 1000. Default: 100.
dict
Response Syntax
{
'creditAllocationHistoryList': [
{
'creditId': 'string',
'creditAmount': {
'currencyCode': 'string',
'currencyAmount': 'string'
},
'description': 'string',
'accountId': 'string',
'appliedServiceName': 'string',
'billingMonth': 'string',
'isEstimatedBill': True|False
},
],
'partialResults': True|False,
'failedMonths': [
'string',
],
'nextToken': 'string'
}
Response Structure
(dict) --
creditAllocationHistoryList (list) --
Allocation entries sorted by billingMonth in descending order.
(dict) --
A single entry in the credit allocation history, representing how a credit was applied to a specific service during a billing month.
creditId (string) --
The identifier of the credit that was applied.
creditAmount (dict) --
The amount of credit applied. Negative values represent credits that reduced the bill.
currencyCode (string) --
The ISO 4217 currency code for the amount (for example, USD).
currencyAmount (string) --
The amount as a decimal string (for example, "743.21"). Negative values represent credits that reduce a bill.
description (string) --
A human-readable description of the credit allocation.
accountId (string) --
The Amazon Web Services account the credit was applied to.
appliedServiceName (string) --
The Amazon Web Services service the credit was applied to.
billingMonth (string) --
The billing month of the application in YYYY-MM format.
isEstimatedBill (boolean) --
true when the entry was applied to an in-flight bill that has not yet been finalized.
partialResults (boolean) --
true when data could not be retrieved for one or more billing months. The failedMonths field lists which months are missing.
failedMonths (list) --
Billing months in YYYY-MM format that failed to return data. Non-empty only when partialResults is true.
(string) --
nextToken (string) --
Pagination token. Present when more pages are available; null when there are no more results.
Updates billing preferences for the specified feature. Each feature targets a distinct billing capability and has its own set of supported keys. The action sets the value for each provided key; keys not present in the request are unchanged.
Sharing keys ( RI_SHARING, CREDIT_SHARING, CREDIT_LEVEL_SHARING, and sharing keys under CREDIT_PREFERENCE_OPTIONS) may only be set by the management account of a consolidated billing family. The credit/{creditId}/status key may be set by member accounts for credits they own, or by the management account for any credit in the family.
See also: AWS API Documentation
Request Syntax
client.update_billing_preferences(
feature='RI_SHARING'|'RI_SHARING_HISTORY'|'CREDIT_SHARING'|'CREDIT_SHARING_HISTORY'|'CREDIT_LEVEL_SHARING'|'BILLING_ALERTS'|'CREDIT_PREFERENCE_OPTIONS',
billingPreferencesPerKey=[
{
'key': 'string',
'value': 'ENABLED'|'DISABLED'
},
]
)
string
[REQUIRED]
The feature to update. Valid values: BILLING_ALERTS, RI_SHARING, CREDIT_SHARING, CREDIT_LEVEL_SHARING, CREDIT_PREFERENCE_OPTIONS. The history features ( RI_SHARING_HISTORY and CREDIT_SHARING_HISTORY) are read-only and cannot be updated.
list
[REQUIRED]
Key/value pairs to apply. All keys in a single request must be valid for the specified feature and must not be duplicated. For CREDIT_PREFERENCE_OPTIONS, all keys must reference the same creditId.
(dict) --
A single key/value entry used to update a billing preference.
key (string) -- [REQUIRED]
The preference key. Format depends on the feature being updated.
value (string) -- [REQUIRED]
The preference value. Valid values: ENABLED or DISABLED.
dict
Response Syntax
{}
Response Structure
(dict) --