AWS SDK for PHP 3.x

Client: Aws\SavingsPlans\SavingsPlansClient

Service ID: savingsplans

Version: 2019-06-28

This page describes the parameters and results for the operations of the AWS Savings Plans (2019-06-28), and shows how to use the Aws\SavingsPlans\SavingsPlansClient object to call the described operations. This documentation is specific to the 2019-06-28 API version of the service.

Operation Summary

Each of the following operations can be created from a client using $client->getCommand('CommandName'), where "CommandName" is the name of one of the following operations. Note: a command is a value that encapsulates an operation and the parameters used to create an HTTP request.

You can also create and send a command immediately using the magic methods available on a client object: $client->commandName(/* parameters */). You can send the command asynchronously (returning a promise) by appending the word "Async" to the operation name: $client->commandNameAsync(/* parameters */).

CreateSavingsPlan ( array $params = [] ): Creates a Savings Plan.
DeleteQueuedSavingsPlan ( array $params = [] ): Deletes the queued purchase for the specified Savings Plan.
DescribeSavingsPlanRates ( array $params = [] ): Describes the rates for the specified Savings Plan.
DescribeSavingsPlans ( array $params = [] ): Describes the specified Savings Plans.
DescribeSavingsPlansOfferingRates ( array $params = [] ): Describes the offering rates for the specified Savings Plans.
DescribeSavingsPlansOfferings ( array $params = [] ): Describes the offerings for the specified Savings Plans.
ListTagsForResource ( array $params = [] ): Lists the tags for the specified resource.
ReturnSavingsPlan ( array $params = [] ): Returns the specified Savings Plan.
TagResource ( array $params = [] ): Adds the specified tags to the specified resource.
UntagResource ( array $params = [] ): Removes the specified tags from the specified resource.

Operations

CreateSavingsPlan

$result = $client->createSavingsPlan([/* ... */]);
$promise = $client->createSavingsPlanAsync([/* ... */]);

Creates a Savings Plan.

Parameter Syntax

$result = $client->createSavingsPlan([
    'clientToken' => '<string>',
    'commitment' => '<string>', // REQUIRED
    'purchaseTime' => <integer || string || DateTime>,
    'savingsPlanOfferingId' => '<string>', // REQUIRED
    'tags' => ['<string>', ...],
    'upfrontPaymentAmount' => '<string>',
]);

Parameter Details

Members

clientToken

Type: string

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

commitment

Required: Yes
Type: string

The hourly commitment, in the same currency of the savingsPlanOfferingId. This is a value between 0.001 and 1 million. You cannot specify more than five digits after the decimal point.

purchaseTime

Type: timestamp (string|DateTime or anything parsable by strtotime)

The purchase time of the Savings Plan in UTC format (YYYY-MM-DDTHH:MM:SSZ).

savingsPlanOfferingId

Required: Yes
Type: string

The ID of the offering.

tags

Type: Associative array of custom strings keys (TagKey) to strings

One or more tags.

upfrontPaymentAmount

Type: string

The up-front payment amount. This is a whole number between 50 and 99 percent of the total value of the Savings Plan. This parameter is only supported if the payment option is Partial Upfront.

Result Syntax

[
    'savingsPlanId' => '<string>',
]

Result Details

Members

savingsPlanId

Type: string

The ID of the Savings Plan.

Errors

ResourceNotFoundException:
The specified resource was not found.
ValidationException:
One of the input parameters is not valid.
InternalServerException:
An unexpected error occurred.
ServiceQuotaExceededException:
A service quota has been exceeded.

DeleteQueuedSavingsPlan

$result = $client->deleteQueuedSavingsPlan([/* ... */]);
$promise = $client->deleteQueuedSavingsPlanAsync([/* ... */]);

Deletes the queued purchase for the specified Savings Plan.

Parameter Syntax

$result = $client->deleteQueuedSavingsPlan([
    'savingsPlanId' => '<string>', // REQUIRED
]);

Parameter Details

Members

savingsPlanId

Required: Yes
Type: string

The ID of the Savings Plan.

Result Syntax

[]

Result Details

The results for this operation are always empty.

Errors

ValidationException:
One of the input parameters is not valid.
ResourceNotFoundException:
The specified resource was not found.
InternalServerException:
An unexpected error occurred.
ServiceQuotaExceededException:
A service quota has been exceeded.

DescribeSavingsPlanRates

$result = $client->describeSavingsPlanRates([/* ... */]);
$promise = $client->describeSavingsPlanRatesAsync([/* ... */]);

Describes the rates for the specified Savings Plan.

Parameter Syntax

$result = $client->describeSavingsPlanRates([
    'filters' => [
        [
            'name' => 'region|instanceType|productDescription|tenancy|productType|serviceCode|usageType|operation',
            'values' => ['<string>', ...],
        ],
        // ...
    ],
    'maxResults' => <integer>,
    'nextToken' => '<string>',
    'savingsPlanId' => '<string>', // REQUIRED
]);

Parameter Details

Members

filters

Type: Array of SavingsPlanRateFilter structures

The filters.

maxResults

Type: int

The maximum number of results to return with a single call. To retrieve additional results, make another call with the returned token value.

nextToken

Type: string

The token for the next page of results.

savingsPlanId

Required: Yes
Type: string

The ID of the Savings Plan.

Result Syntax

[
    'nextToken' => '<string>',
    'savingsPlanId' => '<string>',
    'searchResults' => [
        [
            'currency' => 'CNY|USD',
            'operation' => '<string>',
            'productType' => 'EC2|Fargate|Lambda|SageMaker',
            'properties' => [
                [
                    'name' => 'region|instanceType|instanceFamily|productDescription|tenancy',
                    'value' => '<string>',
                ],
                // ...
            ],
            'rate' => '<string>',
            'serviceCode' => 'AmazonEC2|AmazonECS|AmazonEKS|AWSLambda|AmazonSageMaker',
            'unit' => 'Hrs|Lambda-GB-Second|Request',
            'usageType' => '<string>',
        ],
        // ...
    ],
]

Result Details

Members

nextToken

Type: string

The token to use to retrieve the next page of results. This value is null when there are no more results to return.

savingsPlanId

Type: string

The ID of the Savings Plan.

searchResults

Type: Array of SavingsPlanRate structures

Information about the Savings Plan rates.

Errors

ResourceNotFoundException:
The specified resource was not found.
ValidationException:
One of the input parameters is not valid.

DescribeSavingsPlans

$result = $client->describeSavingsPlans([/* ... */]);
$promise = $client->describeSavingsPlansAsync([/* ... */]);

Describes the specified Savings Plans.

Parameter Syntax

$result = $client->describeSavingsPlans([
    'filters' => [
        [
            'name' => 'region|ec2-instance-family|commitment|upfront|term|savings-plan-type|payment-option|start|end',
            'values' => ['<string>', ...],
        ],
        // ...
    ],
    'maxResults' => <integer>,
    'nextToken' => '<string>',
    'savingsPlanArns' => ['<string>', ...],
    'savingsPlanIds' => ['<string>', ...],
    'states' => ['<string>', ...],
]);

Parameter Details

Members

filters

Type: Array of SavingsPlanFilter structures

The filters.

maxResults

Type: int

The maximum number of results to return with a single call. To retrieve additional results, make another call with the returned token value.

nextToken

Type: string

The token for the next page of results.

savingsPlanArns

Type: Array of strings

The Amazon Resource Names (ARN) of the Savings Plans.

savingsPlanIds

Type: Array of strings

The IDs of the Savings Plans.

states

Type: Array of strings

The current states of the Savings Plans.

Result Syntax

[
    'nextToken' => '<string>',
    'savingsPlans' => [
        [
            'commitment' => '<string>',
            'currency' => 'CNY|USD',
            'description' => '<string>',
            'ec2InstanceFamily' => '<string>',
            'end' => '<string>',
            'offeringId' => '<string>',
            'paymentOption' => 'All Upfront|Partial Upfront|No Upfront',
            'productTypes' => ['<string>', ...],
            'recurringPaymentAmount' => '<string>',
            'region' => '<string>',
            'returnableUntil' => '<string>',
            'savingsPlanArn' => '<string>',
            'savingsPlanId' => '<string>',
            'savingsPlanType' => 'Compute|EC2Instance|SageMaker',
            'start' => '<string>',
            'state' => 'payment-pending|payment-failed|active|retired|queued|queued-deleted|pending-return|returned',
            'tags' => ['<string>', ...],
            'termDurationInSeconds' => <integer>,
            'upfrontPaymentAmount' => '<string>',
        ],
        // ...
    ],
]

Result Details

Members

nextToken

Type: string

The token to use to retrieve the next page of results. This value is null when there are no more results to return.

savingsPlans

Type: Array of SavingsPlan structures

Information about the Savings Plans.

Errors

InternalServerException:
An unexpected error occurred.
ValidationException:
One of the input parameters is not valid.

DescribeSavingsPlansOfferingRates

$result = $client->describeSavingsPlansOfferingRates([/* ... */]);
$promise = $client->describeSavingsPlansOfferingRatesAsync([/* ... */]);

Describes the offering rates for the specified Savings Plans.

Parameter Syntax

$result = $client->describeSavingsPlansOfferingRates([
    'filters' => [
        [
            'name' => 'region|instanceFamily|instanceType|productDescription|tenancy|productId',
            'values' => ['<string>', ...],
        ],
        // ...
    ],
    'maxResults' => <integer>,
    'nextToken' => '<string>',
    'operations' => ['<string>', ...],
    'products' => ['<string>', ...],
    'savingsPlanOfferingIds' => ['<string>', ...],
    'savingsPlanPaymentOptions' => ['<string>', ...],
    'savingsPlanTypes' => ['<string>', ...],
    'serviceCodes' => ['<string>', ...],
    'usageTypes' => ['<string>', ...],
]);

Parameter Details

Members

filters

Type: Array of SavingsPlanOfferingRateFilterElement structures

The filters.

maxResults

Type: int

The maximum number of results to return with a single call. To retrieve additional results, make another call with the returned token value.

nextToken

Type: string

The token for the next page of results.

operations

Type: Array of strings

The specific Amazon Web Services operation for the line item in the billing report.

products

Type: Array of strings

The Amazon Web Services products.

savingsPlanOfferingIds

Type: Array of strings

The IDs of the offerings.

savingsPlanPaymentOptions

Type: Array of strings

The payment options.

savingsPlanTypes

Type: Array of strings

The plan types.

serviceCodes

Type: Array of strings

The services.

usageTypes

Type: Array of strings

The usage details of the line item in the billing report.

Result Syntax

[
    'nextToken' => '<string>',
    'searchResults' => [
        [
            'operation' => '<string>',
            'productType' => 'EC2|Fargate|Lambda|SageMaker',
            'properties' => [
                [
                    'name' => '<string>',
                    'value' => '<string>',
                ],
                // ...
            ],
            'rate' => '<string>',
            'savingsPlanOffering' => [
                'currency' => 'CNY|USD',
                'durationSeconds' => <integer>,
                'offeringId' => '<string>',
                'paymentOption' => 'All Upfront|Partial Upfront|No Upfront',
                'planDescription' => '<string>',
                'planType' => 'Compute|EC2Instance|SageMaker',
            ],
            'serviceCode' => 'AmazonEC2|AmazonECS|AmazonEKS|AWSLambda|AmazonSageMaker',
            'unit' => 'Hrs|Lambda-GB-Second|Request',
            'usageType' => '<string>',
        ],
        // ...
    ],
]

Result Details

Members

nextToken

Type: string

The token to use to retrieve the next page of results. This value is null when there are no more results to return.

searchResults

Type: Array of SavingsPlanOfferingRate structures

Information about the Savings Plans offering rates.

Errors

ValidationException:
One of the input parameters is not valid.
InternalServerException:
An unexpected error occurred.

DescribeSavingsPlansOfferings

$result = $client->describeSavingsPlansOfferings([/* ... */]);
$promise = $client->describeSavingsPlansOfferingsAsync([/* ... */]);

Describes the offerings for the specified Savings Plans.

Parameter Syntax

$result = $client->describeSavingsPlansOfferings([
    'currencies' => ['<string>', ...],
    'descriptions' => ['<string>', ...],
    'durations' => [<integer>, ...],
    'filters' => [
        [
            'name' => 'region|instanceFamily',
            'values' => ['<string>', ...],
        ],
        // ...
    ],
    'maxResults' => <integer>,
    'nextToken' => '<string>',
    'offeringIds' => ['<string>', ...],
    'operations' => ['<string>', ...],
    'paymentOptions' => ['<string>', ...],
    'planTypes' => ['<string>', ...],
    'productType' => 'EC2|Fargate|Lambda|SageMaker',
    'serviceCodes' => ['<string>', ...],
    'usageTypes' => ['<string>', ...],
]);

Parameter Details

Members

currencies

Type: Array of strings

The currencies.

descriptions

Type: Array of strings

The descriptions.

durations

Type: Array of long (int|float)s

The duration, in seconds.

filters

Type: Array of SavingsPlanOfferingFilterElement structures

The filters.

maxResults

Type: int

The maximum number of results to return with a single call. To retrieve additional results, make another call with the returned token value.

nextToken

Type: string

The token for the next page of results.

offeringIds

Type: Array of strings

The IDs of the offerings.

operations

Type: Array of strings

The specific Amazon Web Services operation for the line item in the billing report.

paymentOptions

Type: Array of strings

The payment options.

planTypes

Type: Array of strings

The plan types.

productType

Type: string

The product type.

serviceCodes

Type: Array of strings

The services.

usageTypes

Type: Array of strings

The usage details of the line item in the billing report.

Result Syntax

[
    'nextToken' => '<string>',
    'searchResults' => [
        [
            'currency' => 'CNY|USD',
            'description' => '<string>',
            'durationSeconds' => <integer>,
            'offeringId' => '<string>',
            'operation' => '<string>',
            'paymentOption' => 'All Upfront|Partial Upfront|No Upfront',
            'planType' => 'Compute|EC2Instance|SageMaker',
            'productTypes' => ['<string>', ...],
            'properties' => [
                [
                    'name' => 'region|instanceFamily',
                    'value' => '<string>',
                ],
                // ...
            ],
            'serviceCode' => '<string>',
            'usageType' => '<string>',
        ],
        // ...
    ],
]

Result Details

Members

nextToken

Type: string

The token to use to retrieve the next page of results. This value is null when there are no more results to return.

searchResults

Type: Array of SavingsPlanOffering structures

Information about the Savings Plans offerings.

Errors

ValidationException:
One of the input parameters is not valid.
InternalServerException:
An unexpected error occurred.

ListTagsForResource

$result = $client->listTagsForResource([/* ... */]);
$promise = $client->listTagsForResourceAsync([/* ... */]);

Lists the tags for the specified resource.

Parameter Syntax

$result = $client->listTagsForResource([
    'resourceArn' => '<string>', // REQUIRED
]);

Parameter Details

Members

resourceArn

Required: Yes
Type: string

The Amazon Resource Name (ARN) of the resource.

Result Syntax

[
    'tags' => ['<string>', ...],
]

Result Details

Members

tags

Type: Associative array of custom strings keys (TagKey) to strings

Information about the tags.

Errors

ResourceNotFoundException:
The specified resource was not found.
ValidationException:
One of the input parameters is not valid.
InternalServerException:
An unexpected error occurred.

ReturnSavingsPlan

$result = $client->returnSavingsPlan([/* ... */]);
$promise = $client->returnSavingsPlanAsync([/* ... */]);

Returns the specified Savings Plan.

Parameter Syntax

$result = $client->returnSavingsPlan([
    'clientToken' => '<string>',
    'savingsPlanId' => '<string>', // REQUIRED
]);

Parameter Details

Members

clientToken

Type: string

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

savingsPlanId

Required: Yes
Type: string

The ID of the Savings Plan.

Result Syntax

[
    'savingsPlanId' => '<string>',
]

Result Details

Members

savingsPlanId

Type: string

The ID of the Savings Plan.

Errors

ValidationException:
One of the input parameters is not valid.
ResourceNotFoundException:
The specified resource was not found.
InternalServerException:
An unexpected error occurred.
ServiceQuotaExceededException:
A service quota has been exceeded.

TagResource

$result = $client->tagResource([/* ... */]);
$promise = $client->tagResourceAsync([/* ... */]);

Adds the specified tags to the specified resource.

Parameter Syntax

$result = $client->tagResource([
    'resourceArn' => '<string>', // REQUIRED
    'tags' => ['<string>', ...], // REQUIRED
]);

Parameter Details

Members

resourceArn

Required: Yes
Type: string

The Amazon Resource Name (ARN) of the resource.

tags

Required: Yes
Type: Associative array of custom strings keys (TagKey) to strings

One or more tags. For example, { "tags": {"key1":"value1", "key2":"value2"} }.

Result Syntax

[]

Result Details

The results for this operation are always empty.

Errors

ResourceNotFoundException:
The specified resource was not found.
ServiceQuotaExceededException:
A service quota has been exceeded.
ValidationException:
One of the input parameters is not valid.
InternalServerException:
An unexpected error occurred.

UntagResource

$result = $client->untagResource([/* ... */]);
$promise = $client->untagResourceAsync([/* ... */]);

Removes the specified tags from the specified resource.

Parameter Syntax

$result = $client->untagResource([
    'resourceArn' => '<string>', // REQUIRED
    'tagKeys' => ['<string>', ...], // REQUIRED
]);

Parameter Details

Members

resourceArn

Required: Yes
Type: string

The Amazon Resource Name (ARN) of the resource.

tagKeys

Required: Yes
Type: Array of strings

The tag keys.

Result Syntax

[]

Result Details

The results for this operation are always empty.

Errors

ResourceNotFoundException:
The specified resource was not found.
ValidationException:
One of the input parameters is not valid.
InternalServerException:
An unexpected error occurred.

Shapes

InternalServerException

Description

An unexpected error occurred.

Members

message

Required: Yes
Type: string

ParentSavingsPlanOffering

Description

Information about a Savings Plan offering.

Members

currency

Type: string

The currency.

durationSeconds

Type: long (int|float)

The duration, in seconds.

offeringId

Type: string

The ID of the offering.

paymentOption

Type: string

The payment option.

planDescription

Type: string

The description.

planType

Type: string

The plan type.

ResourceNotFoundException

Description

The specified resource was not found.

Members

message

Required: Yes
Type: string

SavingsPlan

Description

Information about a Savings Plan.

Members

commitment

Type: string

The hourly commitment amount in the specified currency.

currency

Type: string

The currency.

description

Type: string

The description.

ec2InstanceFamily

Type: string

The EC2 instance family.

end

Type: string

The end time.

offeringId

Type: string

The ID of the offering.

paymentOption

Type: string

The payment option.

productTypes

Type: Array of strings

The product types.

recurringPaymentAmount

Type: string

The recurring payment amount.

region

Type: string

The Amazon Web Services Region.

returnableUntil

Type: string

The time until when a return for the Savings Plan can be requested. If the Savings Plan is not returnable, the field reflects the Savings Plan start time.

savingsPlanArn

Type: string

The Amazon Resource Name (ARN) of the Savings Plan.

savingsPlanId

Type: string

The ID of the Savings Plan.

savingsPlanType

Type: string

The plan type.

start

Type: string

The start time.

state

Type: string

The current state.

tags

Type: Associative array of custom strings keys (TagKey) to strings

One or more tags.

termDurationInSeconds

Type: long (int|float)

The duration of the term, in seconds.

upfrontPaymentAmount

Type: string

The up-front payment amount.

SavingsPlanFilter

Description

Information about a Savings Plan filter.

Members

name

Type: string

The filter name.

values

Type: Array of strings

The filter value.

SavingsPlanOffering

Description

Information about a Savings Plan offering.

Members

currency

Type: string

The currency.

description

Type: string

The description.

durationSeconds

Type: long (int|float)

The duration, in seconds.

offeringId

Type: string

The ID of the offering.

operation

Type: string

The specific Amazon Web Services operation for the line item in the billing report.

paymentOption

Type: string

The payment option.

planType

Type: string

The plan type.

productTypes

Type: Array of strings

The product type.

properties

Type: Array of SavingsPlanOfferingProperty structures

The properties.

serviceCode

Type: string

The service.

usageType

Type: string

The usage details of the line item in the billing report.

SavingsPlanOfferingFilterElement

Description

Information about a Savings Plan offering filter.

Members

name

Type: string

The filter name.

values

Type: Array of strings

The filter values.

SavingsPlanOfferingProperty

Description

Information about a Savings Plan offering property.

Members

name

Type: string

The property name.

value

Type: string

The property value.

SavingsPlanOfferingRate

Description

Information about a Savings Plan offering rate.

Members

operation

Type: string

The specific Amazon Web Services operation for the line item in the billing report.

productType

Type: string

The product type.

properties

Type: Array of SavingsPlanOfferingRateProperty structures

The properties.

rate

Type: string

The Savings Plan rate.

savingsPlanOffering

Type: ParentSavingsPlanOffering structure

The Savings Plan offering.

serviceCode

Type: string

The service.

unit

Type: string

The unit.

usageType

Type: string

The usage details of the line item in the billing report.

SavingsPlanOfferingRateFilterElement

Description

Information about a Savings Plan offering rate filter.

Members

name

Type: string

The filter name.

values

Type: Array of strings

The filter values.

SavingsPlanOfferingRateProperty

Description

Information about a Savings Plan offering rate property.

Members

name

Type: string

The property name.

value

Type: string

The property value.

SavingsPlanRate

Description

Information about a Savings Plan rate.

Members

currency

Type: string

The currency.

operation

Type: string

The specific Amazon Web Services operation for the line item in the billing report.

productType

Type: string

The product type.

properties

Type: Array of SavingsPlanRateProperty structures

The properties.

rate

Type: string

The rate.

serviceCode

Type: string

The service.

unit

Type: string

The unit.

usageType

Type: string

The usage details of the line item in the billing report.

SavingsPlanRateFilter

Description

Information about a Savings Plan rate filter.

Members

name

Type: string

The filter name.

values

Type: Array of strings

The filter values.

SavingsPlanRateProperty

Description

Information about a Savings Plan rate property.

Members

name

Type: string

The property name.

value

Type: string

The property value.

ServiceQuotaExceededException

Description

A service quota has been exceeded.

Members

message

Required: Yes
Type: string

ValidationException

Description

One of the input parameters is not valid.

Members

message

Required: Yes
Type: string

AWS Savings Plans 2019-06-28

Operation Summary

Operations

CreateSavingsPlan

Parameter Syntax

Parameter Details

Members

Result Syntax

Result Details

Members

Errors

DeleteQueuedSavingsPlan

Parameter Syntax

Parameter Details

Members

Result Syntax

Result Details

Errors

DescribeSavingsPlanRates

Parameter Syntax

Parameter Details

Members

Result Syntax

Result Details

Members

Errors

DescribeSavingsPlans

Parameter Syntax

Parameter Details

Members

Result Syntax

Result Details

Members

Errors

DescribeSavingsPlansOfferingRates

Parameter Syntax

Parameter Details

Members

Result Syntax

Result Details

Members

Errors

DescribeSavingsPlansOfferings

Parameter Syntax

Parameter Details

Members

Result Syntax

Result Details

Members

Errors

ListTagsForResource

Parameter Syntax

Parameter Details

Members

Result Syntax

Result Details

Members

Errors

ReturnSavingsPlan

Parameter Syntax

Parameter Details

Members

Result Syntax

Result Details

Members

Errors

TagResource

Parameter Syntax

Parameter Details

Members

Result Syntax

Result Details

Errors

UntagResource

Parameter Syntax

Parameter Details

Members

Result Syntax

Result Details

Errors