Select your cookie preferences

We use essential cookies and similar tools that are necessary to provide our site and services. We use performance cookies to collect anonymous statistics, so we can understand how customers use our site and make improvements. Essential cookies cannot be deactivated, but you can choose “Customize” or “Decline” to decline performance cookies.

If you agree, AWS and approved third parties will also use cookies to provide useful site features, remember your preferences, and display relevant content, including relevant advertising. To accept or decline all non-essential cookies, choose “Accept” or “Decline.” To make more detailed choices, choose “Customize.”

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