Amazon Elastic Compute Cloud
API Reference (API Version 2013-02-01)
AWS Documentation » Amazon EC2 » API Reference » Actions » PurchaseReservedInstancesOffering
« PreviousNext »
View the PDF for this guide.Go to the AWS Discussion Forum for this product.Did this page help you?  Yes | No |  Tell us about it...

PurchaseReservedInstancesOffering

Description

Purchases a Reserved Instance for use with your account. With Amazon EC2 Reserved Instances, you obtain a capacity reservation for a certain instance configuration over a specified period of time. You pay a lower usage rate than with On-Demand instances for the time that you actually use the capacity reservation.

Starting with the 2011-11-01 API version, AWS expanded its offering of Reserved Instances to address a range of projected instance usage. There are three types of Reserved Instances based on customer utilization levels: Heavy Utilization, Medium Utilization, and Light Utilization.

The Medium Utilization offering type is equivalent to the Reserved Instance offering available before API version 2011-11-01. If you are using tools that predate the 2011-11-01 API version, DescribeReservedInstancesOfferings will only list information about the Medium Utilization Reserved Instance offering type.

For information about Reserved Instance pricing tiers, go to Understanding Reserved Instance pricing tiers in the Amazon Elastic Compute Cloud User Guide. For more information about Reserved Instances, go to Reserved Instances also in the Amazon Elastic Compute Cloud User Guide.

You determine the type of the Reserved Instances offerings by including the optional offeringType parameter when calling DescribeReservedInstancesOfferings. After you've identified the Reserved Instance with the offering type you want, specify its ReservedInstancesOfferingId when you call PurchaseReservedInstancesOffering.

Starting with the 2012-08-15 API version, you can also purchase Reserved Instances from the Reserved Instance Marketplace. The Reserved Instance Marketplace matches sellers who want to resell Reserved Instance capacity that they no longer need with buyers who want to purchase additional capacity. Reserved Instances bought and sold through the Reserved Instance Marketplace work like any other Reserved Instances.

By default, with the 2012-08-15 API version, DescribeReservedInstancesOfferings returns information about Amazon EC2 Reserved Instances available directly from AWS, plus instance offerings available on the Reserved Instance Marketplace. If you are using tools that predate the 2012-08-15 API version, the DescribeReservedInstancesOfferings action will only list information about Amazon EC2 Reserved Instances available directly from AWS.

For more information about the Reserved Instance Marketplace, go to Reserved Instance Marketplace in the Amazon Elastic Compute Cloud User Guide.

You determine the Reserved Instance Marketplace offerings by specifying true for the optional includeMarketplace parameter when calling DescribeReservedInstancesOfferings. After you've identified the Reserved Instance with the offering type you want, specify its reservedInstancesOfferingId when you call PurchaseReservedInstancesOffering.

Request Parameters

reservedInstancesOfferingId

The ID of the Reserved Instance offering you want to purchase.

Type: String

Default: None

Required: Yes

instanceCount

The number of Reserved Instances to purchase.

Type: Integer

Default: None

Required: Yes

limitPrice

Specified for Reserved Instance Marketplace offerings to limit the total order and ensure that the Reserved Instances are not purchased at unexpected prices.

Type: ReservedInstanceLimitPriceType

Required: No

Response Elements

The following elements are returned in a PurchaseReservedInstancesOfferingResponse element.

requestId

The ID of the request.

Type: xsd:string

reservedInstancesId

The IDs of the purchased Reserved Instances.

Type: xsd:string

Examples

Set the limit price for Reserved Instance Marketplace purchase

This example uses LimitPrice to limit the total purchase order of Reserved Instances from Reserved Instance Marketplace.

https://ec2.amazonaws.com/?Action=PurchaseReservedInstancesOffering
&ReservedInstancesOfferingId=4b2293b4-5813-4cc8-9ce3-1957fc1dcfc8
&LimitPrice.Amount=200
&InstanceCount=2
&AUTHPARAMS

The response looks like the following example.

<PurchaseReservedInstancesOfferingResponse xmlns="http://ec2.amazonaws.com/doc/2013-02-01/">
   <requestId>59dbff89-35bd-4eac-99ed-be587EXAMPLE</requestId> 
   <reservedInstancesId>af9f760e-c1c1-449b-8128-1342d3a6927a</reservedInstancesId> 
</PurchaseReservedInstancesOfferingResponse>

Example Request

This example illustrates a purchase of a Reserved Instances offering.

https://ec2.amazonaws.com/?Action=PurchaseReservedInstancesOffering
&ReservedInstancesOfferingId=4b2293b4-5813-4cc8-9ce3-1957fc1dcfc8
&InstanceCount=2
&AUTHPARAMS

Example Response

<PurchaseReservedInstancesOfferingResponse xmlns="http://ec2.amazonaws.com/doc/2013-02-01/">
   <requestId>59dbff89-35bd-4eac-99ed-be587EXAMPLE</requestId> 
   <reservedInstancesId>af9f760e-c1c1-449b-8128-1342d3a6927a</reservedInstancesId> 
</PurchaseReservedInstancesOfferingResponse>
Document Conventions« PreviousNext »
Terms of UseDid this page help you?  Yes | No |  Tell us about it...