Programmatic Savings Plans Management with AWS CLI and SDK

aws ce start-commitment-purchase-analysis \
  --commitment-purchase-analysis-configuration '{
  "SavingsPlansPurchaseAnalysisConfiguration": {
    "AccountScope": "PAYER",
    "AnalysisType": "CUSTOM_COMMITMENT",
    "LookBackTimePeriod": {
      "Start": "2026-03-01",
      "End": "2026-04-21"
    },
    "SavingsPlansToAdd": [
      {
        "SavingsPlansType": "COMPUTE_SP",
        "TermInYears": "ONE_YEAR",
        "PaymentOption": "NO_UPFRONT",
        "SavingsPlansCommitment": 10.0
      }
    ]
  }
}'
# "LookBackTimePeriod" can be a max of recent 60 days
# "SavingsPlansCommitment" can be specified only for custom_commitment analysis type

This analysis runs asynchronously and returns detailed projections for each scenario. You can compare Compute versus Elastic Compute Cloud (EC2) Instance Savings Plans, one-year versus three-year terms, different payment options, and various commitment levels. The analysis provides comprehensive insights into projected savings, coverage, utilization, and ROI for each scenario.

Retrieve your analysis results with:

aws ce get-commitment-purchase-analysis --analysis-id "analysis-123456789"

Key consideration: Whether you’re migrating workloads or launching new services, validate recommendations against your ramp-up plan. The future doesn’t always resemble the past, please review the recommendation against your roadmap.

After completing your analysis, if you plan to purchase an EC2 Instance Savings Plan, review available offerings in your target region since offerings will vary by region. This makes sure you’re making region-specific commitments based on region-specific usage:

aws savingsplans describe-savings-plans-offerings \
--filters [name="region",values="us-east-1"] \
--query 'savingsPlanOfferings[*].[savingsPlanOfferingId,duration,paymentOption]'
#customize filters and query field as required, remove if you want to see all available offerings.

This step is not required for Compute, Database, and SageMaker Savings Plans since those recommendations take into account all eligible resources regardless of instance family, size, or region.

Phase 2: Executing the Purchase of Savings Plans

Now you are ready to create a Savings Plan purchase. The following is an example of CLI command that can be used to make the purchase. A Savings Plan is a one or three year financial commitment. Verify the commitment amount and estimated net savings before executing the purchase. If a purchase is made in error, you may be able to return it within 7 days, provided:

• The commitment is less than $100 per hour, AND
• The return is requested within the same calendar month as the purchase

Commitments of $100 per hour or more cannot be returned. There is also a limit of 10 returns per year.

aws savingsplans create-savings-plan \
 --savings-plan-offering-id offering-id \
 --commitment "1000.00" \
 --client-token $(uuidgen)
# commitment 1000.00 — replace the 1000 with required hourly $ commitment value

Important: The ‘client-token’ ensures idempotency and avoids accidental duplicate purchase.

After the purchase, you can verify a successful execution using the CLI command below:

aws savingsplans describe-savings-plan-rates \
  --savings-plan-id sp-1234567890abcdef0 \
  --query 'searchResults[].[productType,serviceCode,usageType,operation,rate]' \
  --output table
# customize query and output field as required

Phase 3: Continuous Monitoring

Review your Savings Plans portfolio periodically using the following CLI command:

aws savingsplans describe-savings-plans \
  --filters [name="region",values="us-east-1"] \
  --query 'savingsPlans[].[savingsPlanId,savingsPlanType,state,commitment,currency]' \
  --output table
#customize filters, query and output field as required, remove if you want to see all active Savings Plans

This helps you view your commitment profile to identify opportunities for additional savings and allows you to iteratively purchase additional Savings Plans as your workloads grow. Before making any new purchase, review the net savings projections from your Phase 1 analysis to ensure the commitment aligns with your actual usage patterns.

How to Handle Complex Savings Plans Workflows with SDK

While the CLI works well for scripts and one-off operations, an SDK approach provides programmatic control over error handling, logging, and integration with your existing tools. It also provides an ability to integrate with CI/CD pipelines, monitoring systems, or FinOps dashboards.

Below is the example snippet using SDK to purchase Savings Plans:

import boto3
import botocore
import uuid

def purchase_savings_plan():
    client = boto3.client('savingsplans')

    try:
        # List available offerings
        offerings = client.describe_savings_plans_offerings(
            filters=[
                {
                    'name': 'REGION',
                    'values': ['us-east-1']
                }
            ]
        )

        # Create savings plan
        # replace the 1000 with required hourly $ commitment value
        response = client.create_savings_plan(
            savingsPlanOfferingId='offering-id',
            commitment='1000.00',
            clientToken=str(uuid.uuid4())
        )

        return response

    except botocore.exceptions.ClientError as e:
        if e.response['Error']['Code'] == 'ValidationException':
            print("Invalid parameters provided")
        elif e.response['Error']['Code'] == 'AccessDeniedException':
            print("Insufficient permissions")
        else:
            print(f"Unexpected error: {e}")
        raise

# Execute the purchase
result = purchase_savings_plan()
print(f"Savings Plan created: {result['savingsPlanId']}")