AWS Billing

2026/11/17 - AWS Billing - 2 new 2 updated api methods

Changes  Adds the SplitCredit and TransferCredit APIs to split or transfer credits, and adds benefit level sharing for Reserved Instances and Savings Plans to GetBillingPreferences and UpdateBillingPreferences.

TransferCredit (new) Link ¶

Moves a credit to another account in the same consolidated billing family. The credit keeps its ID, balance, end date, and applicable products. Only the account that owns the credit changes.

The transfer removes the credit's sharing settings. The new owner or the payer can set them again. Any amount reserved for a bill that isn't finalized moves with the credit and still applies to that bill.

You must be the payer of both accounts. You can't transfer a credit that has ended, has no available balance, or is the original credit of a split. A transfer creates no credit, so it doesn't count toward the split limit, and the payer can transfer the credit back. This operation is idempotent and supports a dry run.

See also: AWS API Documentation

Request Syntax

client.transfer_credit(
    creditId='string',
    destinationAccountId='string',
    clientToken='string',
    dryRun=True|False
)
type creditId:

string

param creditId:

[REQUIRED]

The ID of the credit to transfer.

type destinationAccountId:

string

param destinationAccountId:

[REQUIRED]

The Amazon Web Services account ID that becomes the owner of the credit. The account must be in your consolidated billing family and must not be the current owner.

type clientToken:

string

param clientToken:

A unique, case-sensitive identifier that you provide to ensure that the operation completes no more than one time. If you retry a successful request with the same client token and parameters, the retry completes without performing any further actions. If you reuse a client token with different parameters, the request fails with a ValidationException.

This field is autopopulated if not provided.

type dryRun:

boolean

param dryRun:

Specifies whether to validate the request and return the result without changing the credit.

rtype:

dict

returns:

Response Syntax

{
    'sourceCreditId': 'string',
    'newCreditId': 'string',
    'destinationAccountId': 'string',
    'amount': 'string',
    'dryRun': True|False
}

Response Structure

  • (dict) --

    • sourceCreditId (string) --

      The ID of the transferred credit. The credit keeps this ID.

    • newCreditId (string) --

      Always the same as sourceCreditId, because a transfer moves the credit and creates no new one. A dry run omits this field.

    • destinationAccountId (string) --

      The Amazon Web Services account ID that owns the credit after the transfer.

    • amount (string) --

      The available balance of the credit, which is its remaining balance minus any amount reserved for a bill that isn't finalized.

    • dryRun (boolean) --

      Specifies whether the request was a dry run. If true, the operation didn't change the credit.

SplitCredit (new) Link ¶

Splits the available balance of a credit into 2 to 99 new credits in the same account, and cancels the original credit. The new credits keep the original credit's end date and applicable products.

The available balance is the remaining balance minus any amount reserved for a bill that isn't finalized. The portions must add up to exactly the available balance. Each portion must be at least 100.00 in the currency of the credit. For example, if the credit is in USD, each portion must be at least USD $100.00. A reserved amount stays on the original credit and still applies to that bill.

A credit and every credit split from it count toward a limit of 100 credits. After a split, you can't split or transfer the original credit. You can split or transfer its new credits, and you can split a credit after you transfer it.

You must own the credit or be the payer of the account that owns it. You can't undo a split. This operation is idempotent and supports a dry run.

See also: AWS API Documentation

Request Syntax

client.split_credit(
    creditId='string',
    portions=[
        {
            'amount': 'string',
            'description': 'string'
        },
    ],
    clientToken='string',
    dryRun=True|False
)
type creditId:

string

param creditId:

[REQUIRED]

The ID of the credit to split.

type portions:

list

param portions:

[REQUIRED]

The new credits to create, one for each portion, in the order listed.

  • (dict) --

    One new credit to create from a split.

    • amount (string) -- [REQUIRED]

      The amount of the new credit, in the currency of the credit that you split. The amount must be at least 100.00 in that currency. For example, if the credit is in USD, the amount must be at least USD $100.00.

    • description (string) --

      The description of the new credit. If you omit it, the new credit gets the original credit's description followed by its position in the request, for example MAP credit - 1/3. If you split that credit again, the name extends, for example MAP credit - 1/3 - 2/2. A generated name is at most 93 characters. If it would be longer, the name keeps only the beginning of the original description.

type clientToken:

string

param clientToken:

A unique, case-sensitive identifier that you provide to ensure that the operation completes no more than one time. If you retry a successful request with the same client token and parameters, the retry completes without performing any further actions. If you reuse a client token with different parameters, the request fails with a ValidationException.

This field is autopopulated if not provided.

type dryRun:

boolean

param dryRun:

Specifies whether to validate the request and return the result without changing any credit.

rtype:

dict

returns:

Response Syntax

{
    'parentCreditId': 'string',
    'childCredits': [
        {
            'creditId': 'string',
            'amount': 'string'
        },
    ],
    'dryRun': True|False
}

Response Structure

  • (dict) --

    • parentCreditId (string) --

      The ID of the credit that was split.

    • childCredits (list) --

      The new credits, in the order of the requested portions.

      • (dict) --

        A new credit that a split created.

        • creditId (string) --

          The ID of the new credit. A dry run omits this field.

        • amount (string) --

          The amount of the new credit.

    • dryRun (boolean) --

      Specifies whether the request was a dry run. If true, the operation didn't change any credit.

GetBillingPreferences (updated) Link ¶
Changes (request, response)
Request
{'features': {'BENEFIT_LEVEL_SHARING'}}
Response
{'billingPreferences': {'feature': {'BENEFIT_LEVEL_SHARING'}}}

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, per-credit options, and which accounts an individual Reserved Instance or Savings Plan is shared with.

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'|'BENEFIT_LEVEL_SHARING',
    ],
    filters=[
        {
            'name': 'PREFERENCE_KEY',
            'value': [
                'string',
            ]
        },
    ]
)
type nextToken:

string

param nextToken:

Pagination token from a previous response. Pass the value returned in nextToken to retrieve the next page of results.

type maxResults:

integer

param maxResults:

The maximum number of records to return per page. Range: 1 to 50. Default: 50.

type features:

list

param features:

[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, BENEFIT_LEVEL_SHARING.

  • (string) --

type filters:

list

param filters:

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.

For BENEFIT_LEVEL_SHARING, this filter is required. Specify exactly one value that identifies the Reserved Instance (RI) or Savings Plan (SP), in the form benefit/{ri|sp}/{benefitId}.

  • (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) --

rtype:

dict

returns:

Response Syntax

{
    'billingPreferences': [
        {
            'feature': 'RI_SHARING'|'RI_SHARING_HISTORY'|'CREDIT_SHARING'|'CREDIT_SHARING_HISTORY'|'CREDIT_LEVEL_SHARING'|'BILLING_ALERTS'|'CREDIT_PREFERENCE_OPTIONS'|'BENEFIT_LEVEL_SHARING',
            '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.

UpdateBillingPreferences (updated) Link ¶
Changes (request)
{'feature': {'BENEFIT_LEVEL_SHARING'}}

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.

To set sharing keys ( RI_SHARING, CREDIT_SHARING, CREDIT_LEVEL_SHARING, BENEFIT_LEVEL_SHARING, and sharing keys under CREDIT_PREFERENCE_OPTIONS), you must use the management account of a consolidated billing family. To set the credit/{creditId}/status key, you must own the credit or use the management account of its 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'|'BENEFIT_LEVEL_SHARING',
    billingPreferencesPerKey=[
        {
            'key': 'string',
            'value': 'ENABLED'|'DISABLED'
        },
    ]
)
type feature:

string

param feature:

[REQUIRED]

The feature to update. Valid values: BILLING_ALERTS, RI_SHARING, CREDIT_SHARING, CREDIT_LEVEL_SHARING, CREDIT_PREFERENCE_OPTIONS, BENEFIT_LEVEL_SHARING. The history features ( RI_SHARING_HISTORY and CREDIT_SHARING_HISTORY) are read-only and cannot be updated.

type billingPreferencesPerKey:

list

param billingPreferencesPerKey:

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

For BENEFIT_LEVEL_SHARING, all keys must reference the same Reserved Instance or Savings Plan. To share it with the accounts in one Cost Category rule, send these three keys with the value ENABLED:

  • benefit/{ri|sp}/{benefitId}/sharing/costCategoryArn/{costCategoryArn}

  • benefit/{ri|sp}/{benefitId}/sharing/ruleName/{ruleName}

  • benefit/{ri|sp}/{benefitId}/sharing/mode/{prioritized|restricted}

With prioritized, any benefit that the rule's accounts don't use goes to the rest of your consolidated billing family, following your family sharing settings. With restricted, only the owner and the rule's accounts receive it. The Cost Category must belong to your account. To stop sharing, send the same three keys with the value DISABLED.

For RI_SHARING and CREDIT_SHARING, you can share benefits by account group. Each rule in a Cost Category is one group. Send exactly one of these group keys with the value ENABLED:

  • open-sharing - Share across the whole consolidated billing family, with no groups.

  • costcategory-prioritized/{costCategoryArn} - Share within each group first, then with the rest of the family.

  • costcategory-restricted/{costCategoryArn} - An account in a group shares only with accounts in the same group.

For RI_SHARING, the costcategory- keys use a Cost Category that supports the billing:rispgroupsharing resource type. To use a Cost Category that supports the billing:benefitgroupsharing resource type, use the benefitgroup-prioritized/ or benefitgroup-restricted/ prefix instead. For CREDIT_SHARING, the Cost Category must support the billing:benefitgroupsharing resource type. The Cost Category must belong to your account. GetBillingPreferences returns the group key that is in effect.

  • (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.

rtype:

dict

returns:

Response Syntax

{}

Response Structure

  • (dict) --