SDK for PHP 3.x

AWS Savings Plans 2019-06-28

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