Getting started with the PricingPlanManager API

You can use the AWS CLI or the PricingPlanManager API to create, modify, and cancel flat-rate pricing plan subscriptions programmatically. The PricingPlanManager service manages subscriptions across plan families. Currently, CloudFront (CloudFront flat-rate pricing) is the only supported plan family.

This page provides a sample of the available operations, common workflows, and error handling. For complete API reference documentation, see the PricingPlanManager API Reference.

For information about managing CloudFront flat-rate pricing plans using the CloudFront console, see CloudFront flat-rate pricing plans in the Amazon CloudFront Developer Guide.

Prerequisites

Before you use the PricingPlanManager API, verify the following:

Key concepts

Subscription lifecycle

A pricing plan subscription goes through the following statuses:

Optimistic concurrency (ETag)

All mutating operations use optimistic concurrency control through ETags. When you retrieve a subscription (using GetSubscription or ListSubscriptions), the response includes an eTag value. You must pass this value in the ifMatch parameter (--if-match in the CLI) when you update or cancel the subscription. If the subscription has changed since you retrieved it, the operation fails with a ConflictException.

This mechanism prevents one change from overwriting another.

Two-phase subscription creation

When you create a subscription for a paid plan, you choose an approval mode that controls whether billing starts immediately or requires a separate approval step:

Approval mode recommendation

We recommend using MANUAL approval mode for all programmatic workflows. You cannot cancel or revert an active paid subscription during the current billing period (calendar month). The two-phase approach prevents automated processes from starting billing without human confirmation. Premium plans can cost up to $10,000/mo.

IAM permission separation

To enforce the two-phase pattern, grant your automated workflows (such as deployment pipelines, agents, or service roles) only the pricingplanmanager:CreateSubscription permission. Reserve the pricingplanmanager:ApprovePaidSubscription permission for roles that require human authorization (such as administrator roles used interactively).

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "pricingplanmanager:CreateSubscription",
      "Resource": "*"
    }
  ]
}

IMMEDIATE approval mode permissions

If a caller passes approvalMode: "IMMEDIATE" for a paid plan, the caller must have both the pricingplanmanager:CreateSubscription and pricingplanmanager:ApprovePaidSubscription permissions. The request fails with AccessDeniedException if the caller lacks the approval permission.

Free plan subscriptions are always activated immediately. For Free plans, the approval mode must be IMMEDIATE or omitted; a request that specifies MANUAL is rejected, because Free plans don’t require approval.

Scheduled changes

Some changes don’t take effect immediately:

Pending scheduled changes are recorded in the subscription’s scheduledChange field. You can cancel a pending scheduled change using CancelSubscriptionChange to keep your current plan.

Operations reference

CreateSubscription

Creates a new pricing plan subscription for one or more resources. For CloudFront plans, the resources are CloudFront distribution ARNs and WAF web ACL ARNs.

CLI syntax

aws pricing-plan-manager create-subscription \
    --plan-family <value> \
    --plan-tier <value> \
    [--usage-level <value>] \
    --resource-arns <value> [<value>...] \
    [--approval-mode <value>] \
    [--client-token <value>]

Parameters

Example request (recommended two-phase pattern)

aws pricing-plan-manager create-subscription \
    --plan-family CloudFront \
    --plan-tier PRO \
    --resource-arns \
        arn:aws:cloudfront::111122223333:distribution/EDFDVBD6EXAMPLE \
        arn:aws:wafv2:us-east-1:111122223333:global/webacl/my-web-acl/a1b2c3d4-5678-90ab-cdef-EXAMPLE22222 \
    --approval-mode MANUAL

Example response

{
  "subscription": {
    "arn": "arn:aws:pricingplanmanager:us-east-1:111122223333:subscription/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",
    "planFamily": "CloudFront",
    "planTier": "PRO",
    "resourceArns": [
      "arn:aws:cloudfront::111122223333:distribution/EDFDVBD6EXAMPLE",
      "arn:aws:wafv2:us-east-1:111122223333:global/webacl/my-web-acl/a1b2c3d4-5678-90ab-cdef-EXAMPLE22222"
    ],
    "status": "PENDING_APPROVAL",
    "createdAt": "2026-07-23T10:00:00Z",
    "updatedAt": "2026-07-23T10:00:00Z"
  },
  "eTag": "v1aXample1234"
}

Notes

ApprovePaidSubscription

Approves a subscription that is in PENDING_APPROVAL status. This activates the paid subscription and begins billing.

CLI syntax

aws pricing-plan-manager approve-paid-subscription \
    --arn <value> \
    --if-match <value> \
    [--client-token <value>]

Parameters

Example request

aws pricing-plan-manager approve-paid-subscription \
    --arn arn:aws:pricingplanmanager:us-east-1:111122223333:subscription/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111 \
    --if-match "v1aXample1234"

Example response

{
  "subscription": {
    "arn": "arn:aws:pricingplanmanager:us-east-1:111122223333:subscription/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",
    "planFamily": "CloudFront",
    "planTier": "PRO",
    "resourceArns": [
      "arn:aws:cloudfront::111122223333:distribution/EDFDVBD6EXAMPLE",
      "arn:aws:wafv2:us-east-1:111122223333:global/webacl/my-web-acl/a1b2c3d4-5678-90ab-cdef-EXAMPLE22222"
    ],
    "status": "SYNC_IN_PROGRESS",
    "createdAt": "2026-07-23T10:00:00Z",
    "updatedAt": "2026-07-23T10:01:00Z"
  },
  "eTag": "v2bXample5678"
}

Notes

GetSubscription

Retrieves the details of a single pricing plan subscription.

CLI syntax

aws pricing-plan-manager get-subscription \
    --arn <value>

Parameters

Example request

aws pricing-plan-manager get-subscription \
    --arn arn:aws:pricingplanmanager:us-east-1:111122223333:subscription/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111

Example response

{
  "subscription": {
    "arn": "arn:aws:pricingplanmanager:us-east-1:111122223333:subscription/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",
    "planFamily": "CloudFront",
    "planTier": "BUSINESS",
    "resourceArns": [
      "arn:aws:cloudfront::111122223333:distribution/EDFDVBD6EXAMPLE",
      "arn:aws:wafv2:us-east-1:111122223333:global/webacl/my-web-acl/a1b2c3d4-5678-90ab-cdef-EXAMPLE22222"
    ],
    "status": "ACTIVE",
    "createdAt": "2026-07-23T10:00:00Z",
    "updatedAt": "2026-07-23T12:30:00Z"
  },
  "eTag": "v3cXample9012"
}

Notes

ListSubscriptions

Lists all pricing plan subscriptions in your account.

CLI syntax

aws pricing-plan-manager list-subscriptions \
    [--next-token <value>]

Parameters

Example request

aws pricing-plan-manager list-subscriptions

Example response

{
  "subscriptionSummaries": [
    {
      "arn": "arn:aws:pricingplanmanager:us-east-1:111122223333:subscription/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",
      "planFamily": "CloudFront",
      "planTier": "BUSINESS",
      "resourceArns": [
        "arn:aws:cloudfront::111122223333:distribution/EDFDVBD6EXAMPLE",
        "arn:aws:wafv2:us-east-1:111122223333:global/webacl/my-web-acl/a1b2c3d4-5678-90ab-cdef-EXAMPLE22222"
      ],
      "status": "ACTIVE",
      "createdAt": "2026-07-21T10:00:00Z",
      "updatedAt": "2026-07-23T10:00:00Z",
      "eTag": "v3cXample9012"
    }
  ],
  "nextToken": null
}

UpdateSubscription

Changes the plan tier or usage level of an existing subscription.

CLI syntax

aws pricing-plan-manager update-subscription \
    --arn <value> \
    --if-match <value> \
    [--plan-tier <value>] \
    [--usage-level <value>] \
    [--client-token <value>]

Parameters

You must specify at least one of --plan-tier or --usage-level.

Example request (upgrade)

aws pricing-plan-manager update-subscription \
    --arn arn:aws:pricingplanmanager:us-east-1:111122223333:subscription/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111 \
    --if-match "v3cXample9012" \
    --plan-tier PREMIUM \
    --usage-level CF_PREMIUM_L4

Example response (upgrade)

{
  "subscription": {
    "arn": "arn:aws:pricingplanmanager:us-east-1:111122223333:subscription/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",
    "planFamily": "CloudFront",
    "planTier": "PREMIUM",
    "usageLevel": "CF_PREMIUM_L4",
    "resourceArns": [
      "arn:aws:cloudfront::111122223333:distribution/EDFDVBD6EXAMPLE",
      "arn:aws:wafv2:us-east-1:111122223333:global/webacl/my-web-acl/a1b2c3d4-5678-90ab-cdef-EXAMPLE22222"
    ],
    "status": "ACTIVE",
    "createdAt": "2026-07-23T10:00:00Z",
    "updatedAt": "2026-07-23T14:00:00Z"
  },
  "eTag": "v4dXample3456"
}

Example request (downgrade)

aws pricing-plan-manager update-subscription \
    --arn arn:aws:pricingplanmanager:us-east-1:111122223333:subscription/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111 \
    --if-match "v4dXample3456" \
    --plan-tier PRO

Example response (downgrade)

{
  "subscription": {
    "arn": "arn:aws:pricingplanmanager:us-east-1:111122223333:subscription/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",
    "planFamily": "CloudFront",
    "planTier": "PREMIUM",
    "usageLevel": "CF_PREMIUM_L4",
    "resourceArns": [
      "arn:aws:cloudfront::111122223333:distribution/EDFDVBD6EXAMPLE",
      "arn:aws:wafv2:us-east-1:111122223333:global/webacl/my-web-acl/a1b2c3d4-5678-90ab-cdef-EXAMPLE22222"
    ],
    "status": "SYNC_IN_PROGRESS",
    "scheduledChange": {
      "changeType": "DOWNGRADE",
      "planTier": "PRO"
    },
    "createdAt": "2026-07-23T10:00:00Z",
    "updatedAt": "2026-07-23T15:00:00Z"
  },
  "eTag": "v5eXample7890"
}

Notes

CancelSubscription

Cancels a pricing plan subscription. For paid plans, the cancellation is scheduled for the end of the current billing period. For Free plans, the cancellation takes effect immediately.

CLI syntax

aws pricing-plan-manager cancel-subscription \
    --arn <value> \
    --if-match <value> \
    [--client-token <value>]

Parameters

Example request

aws pricing-plan-manager cancel-subscription \
    --arn arn:aws:pricingplanmanager:us-east-1:111122223333:subscription/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111 \
    --if-match "v4dXample3456"

Example response

{
  "subscription": {
    "arn": "arn:aws:pricingplanmanager:us-east-1:111122223333:subscription/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",
    "planFamily": "CloudFront",
    "planTier": "PREMIUM",
    "usageLevel": "CF_PREMIUM_L4",
    "resourceArns": [
      "arn:aws:cloudfront::111122223333:distribution/EDFDVBD6EXAMPLE",
      "arn:aws:wafv2:us-east-1:111122223333:global/webacl/my-web-acl/a1b2c3d4-5678-90ab-cdef-EXAMPLE22222"
    ],
    "status": "SYNC_IN_PROGRESS",
    "scheduledChange": {
      "changeType": "CANCELLATION"
    },
    "createdAt": "2026-07-23T10:00:00Z",
    "updatedAt": "2026-07-23T16:00:00Z"
  },
  "eTag": "v6fXample1234"
}

Notes

CancelSubscriptionChange

Cancels a pending scheduled change (downgrade or cancellation) on a subscription. The subscription continues with its current plan.

CLI syntax

aws pricing-plan-manager cancel-subscription-change \
    --arn <value> \
    --if-match <value> \
    [--client-token <value>]

Parameters

Example request

aws pricing-plan-manager cancel-subscription-change \
    --arn arn:aws:pricingplanmanager:us-east-1:111122223333:subscription/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111 \
    --if-match "v6fXample1234"

Example response

{
  "subscription": {
    "arn": "arn:aws:pricingplanmanager:us-east-1:111122223333:subscription/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",
    "planFamily": "CloudFront",
    "planTier": "PREMIUM",
    "usageLevel": "CF_PREMIUM_L4",
    "resourceArns": [
      "arn:aws:cloudfront::111122223333:distribution/EDFDVBD6EXAMPLE",
      "arn:aws:wafv2:us-east-1:111122223333:global/webacl/my-web-acl/a1b2c3d4-5678-90ab-cdef-EXAMPLE22222"
    ],
    "status": "ACTIVE",
    "createdAt": "2026-07-23T10:00:00Z",
    "updatedAt": "2026-07-23T17:00:00Z"
  },
  "eTag": "v7gXample5678"
}

Notes

AssociateResourcesToSubscription

Adds one or more resources to an existing subscription. For CloudFront plans, use this to add optional resources (such as a Route 53 hosted zone ARN or a CloudFront KeyValueStore ARN) after the subscription is created.

CLI syntax

aws pricing-plan-manager associate-resources-to-subscription \
    --arn <value> \
    --if-match <value> \
    --resource-arns <value> [<value>...] \
    [--client-token <value>]

Parameters

Example request

aws pricing-plan-manager associate-resources-to-subscription \
    --arn arn:aws:pricingplanmanager:us-east-1:111122223333:subscription/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111 \
    --if-match "v3cXample9012" \
    --resource-arns \
        arn:aws:route53:::hostedzone/Z0123456789ABCDEFGHIJ

Notes

DisassociateResourcesFromSubscription

Removes one or more optional resources from an existing subscription. You cannot remove required resources (for example, for CloudFront plans, the distribution and web ACL are required and cannot be disassociated).

CLI syntax

aws pricing-plan-manager disassociate-resources-from-subscription \
    --arn <value> \
    --if-match <value> \
    --resource-arns <value> [<value>...] \
    [--client-token <value>]

Parameters

Example request

aws pricing-plan-manager disassociate-resources-from-subscription \
    --arn arn:aws:pricingplanmanager:us-east-1:111122223333:subscription/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111 \
    --if-match "v3cXample9012" \
    --resource-arns \
        arn:aws:route53:::hostedzone/Z0123456789ABCDEFGHIJ

Notes

Common workflows

This section shows end-to-end workflows using the AWS CLI.

Subscribe and approve a paid plan

This workflow creates a subscription with manual approval, then approves it.

# Step 1: Create the subscription
read SUBSCRIPTION_ARN ETAG < <(aws pricing-plan-manager create-subscription \
    --plan-family CloudFront \
    --plan-tier BUSINESS \
    --resource-arns \
        arn:aws:cloudfront::111122223333:distribution/EDFDVBD6EXAMPLE \
        arn:aws:wafv2:us-east-1:111122223333:global/webacl/my-web-acl/a1b2c3d4-5678-90ab-cdef-EXAMPLE22222 \
    --approval-mode MANUAL \
    --query '[subscription.arn, eTag]' \
    --output text)

echo "Subscription created: $SUBSCRIPTION_ARN (status: PENDING_APPROVAL)"
echo "ETag: $ETAG"

# Step 2: Approve the subscription
aws pricing-plan-manager approve-paid-subscription \
    --arn "$SUBSCRIPTION_ARN" \
    --if-match "$ETAG"

Upgrade a subscription

This workflow retrieves a subscription, then upgrades it to a higher tier.

# Step 1: Get the current subscription to retrieve the ETag
SUBSCRIPTION_ARN="arn:aws:pricingplanmanager:us-east-1:111122223333:subscription/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111"

# Get current subscription — pull ETag and current tier in one call
read ETAG CURRENT_TIER < <(aws pricing-plan-manager get-subscription \
    --arn "$SUBSCRIPTION_ARN" \
    --query '[eTag, subscription.planTier]' \
    --output text)

echo "Current tier: $CURRENT_TIER"

# Step 2: Upgrade to Premium
aws pricing-plan-manager update-subscription \
    --arn "$SUBSCRIPTION_ARN" \
    --if-match "$ETAG" \
    --plan-tier PREMIUM \
    --usage-level CF_PREMIUM_L3

Downgrade a subscription

This workflow downgrades a subscription. The downgrade is scheduled for the end of the billing period.

# Step 1: Get the current subscription
SUBSCRIPTION_ARN="arn:aws:pricingplanmanager:us-east-1:111122223333:subscription/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111"

ETAG=$(aws pricing-plan-manager get-subscription \
    --arn "$SUBSCRIPTION_ARN" \
    --query 'eTag' \
    --output text)

# Step 2: Downgrade to Pro (takes effect at end of billing period)
aws pricing-plan-manager update-subscription \
    --arn "$SUBSCRIPTION_ARN" \
    --if-match "$ETAG" \
    --plan-tier PRO \
    --query 'subscription.scheduledChange'

Cancel a subscription and undo the cancellation

This workflow cancels a paid subscription, then undoes the cancellation before it takes effect.

SUBSCRIPTION_ARN="arn:aws:pricingplanmanager:us-east-1:111122223333:subscription/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111"

# Step 1: Get the current subscription
ETAG=$(aws pricing-plan-manager get-subscription \
    --arn "$SUBSCRIPTION_ARN" \
    --query 'eTag' \
    --output text)

# Step 2: Cancel the subscription (scheduled for end of billing period)
# Only the ETag is reliably present now — effectiveDate is not populated until sync completes.
NEW_ETAG=$(aws pricing-plan-manager cancel-subscription \
    --arn "$SUBSCRIPTION_ARN" \
    --if-match "$ETAG" \
    --query 'eTag' \
    --output text)

# Step 2b: Poll until the resource is done syncing and the effective date appears
echo "Waiting for scheduled change to sync..."
while true; do
    read STATUS EFFECTIVE_DATE LATEST_ETAG < <(aws pricing-plan-manager get-subscription \
        --arn "$SUBSCRIPTION_ARN" \
        --query '[subscription.status, subscription.scheduledChange.effectiveDate, eTag]' \
        --output text)
    if [ "$EFFECTIVE_DATE" != "None" ] && [ -n "$EFFECTIVE_DATE" ]; then
        break
    fi
    echo "  status: $STATUS (effective date not yet available)"
    sleep 5
done

echo "Cancellation scheduled for: $EFFECTIVE_DATE"

# Step 3: Changed your mind? Cancel the scheduled cancellation
# Use the latest ETag from the poll — the ETag may have changed during sync.
aws pricing-plan-manager cancel-subscription-change \
    --arn "$SUBSCRIPTION_ARN" \
    --if-match "$LATEST_ETAG"

echo "Cancellation undone. Subscription continues as normal."

Plan family specifics

The key concepts, operations, and workflows described earlier apply to all plan families. This section covers the requirements and behavior that are specific to each plan family. CloudFront is currently the only plan family.

Working with the CloudFront plan family

The CloudFront plan family applies flat-rate pricing to a CloudFront distribution and its associated AWS WAF web ACL, Amazon Route 53 hosted zone, and Amazon CloudWatch Logs ingestion. This section covers the CloudFront-specific details you need when you manage CloudFront plan subscriptions programmatically.

For the full description of plan tiers, included features, usage allowances, and unsupported configurations, see CloudFront flat-rate pricing plans in the Amazon CloudFront Developer Guide.

Required and optional resources

When you create a CloudFront plan subscription, the resourceArns list must include:

You can optionally include, at create time or later using AssociateResourcesToSubscription:

Plan tiers

The CloudFront plan family supports the following tiers, which you specify in the planTier parameter:

Higher tiers include all features of the lower tiers plus additional capabilities. For the complete feature matrix and monthly usage allowances, see Features by pricing plan tier in the Amazon CloudFront Developer Guide.

Premium usage levels

The Premium plan offers configurable monthly usage allowances. When you subscribe to or manage a Premium plan, you can select a higher monthly usage allowance from the following levels:

When you select a higher usage level, your monthly price increases and your monthly usage allowance increases accordingly. The features and services included in the Premium plan remain the same at every usage level. You are only changing your usage allowance and flat-rate price.

When you increase your usage level, changes take effect immediately and your price is prorated. When you decrease your usage level, the change takes effect at the beginning of the next billing cycle.

If your application’s baseline usage exceeds 6 B requests or 600 TB per month, contact us for custom pricing.

Create the distribution and web ACL before you subscribe

A CloudFront plan subscription requires both a CloudFront distribution and an AWS WAF web ACL, and both must exist before you create the subscription. Create the web ACL first, so that you can reference its ARN in the distribution configuration. The typical flow is: create the web ACL → create the distribution (referencing the web ACL) → create the subscription (referencing both ARNs). For paid plans, the subscription must also be approved to start billing—either in the same step with IMMEDIATE approval mode, or in a separate step with MANUAL.

Step 1: Create the web ACL

The following example creates a web ACL in the CLOUDFRONT scope with the AWS Managed Rules rule groups that correspond to the default one-click protection applied in the CloudFront console. The AWSManagedRulesCommonRuleSet and AWSManagedRulesAmazonIpReputationList rule groups provide baseline protection suitable for most applications.

aws wafv2 create-web-acl \
    --name my-plan-web-acl \
    --scope CLOUDFRONT \
    --region us-east-1 \
    --default-action Allow={} \
    --visibility-config SampledRequestsEnabled=true,CloudWatchMetricsEnabled=true,MetricName=my-plan-web-acl \
    --rules '[
        {
            "Name": "AWS-AWSManagedRulesCommonRuleSet",
            "Priority": 0,
            "Statement": {
                "ManagedRuleGroupStatement": {
                    "VendorName": "AWS",
                    "Name": "AWSManagedRulesCommonRuleSet"
                }
            },
            "OverrideAction": { "None": {} },
            "VisibilityConfig": {
                "SampledRequestsEnabled": true,
                "CloudWatchMetricsEnabled": true,
                "MetricName": "AWSManagedRulesCommonRuleSet"
            }
        },
        {
            "Name": "AWS-AWSManagedRulesAmazonIpReputationList",
            "Priority": 1,
            "Statement": {
                "ManagedRuleGroupStatement": {
                    "VendorName": "AWS",
                    "Name": "AWSManagedRulesAmazonIpReputationList"
                }
            },
            "OverrideAction": { "None": {} },
            "VisibilityConfig": {
                "SampledRequestsEnabled": true,
                "CloudWatchMetricsEnabled": true,
                "MetricName": "AWSManagedRulesAmazonIpReputationList"
            }
        },
        {
            "Name": "AWS-AWSManagedRulesKnownBadInputsRuleSet",
            "Priority": 2,
            "Statement": {
                "ManagedRuleGroupStatement": {
                    "VendorName": "AWS",
                    "Name": "AWSManagedRulesKnownBadInputsRuleSet"
                }
            },
            "OverrideAction": { "None": {} },
            "VisibilityConfig": {
                "SampledRequestsEnabled": true,
                "CloudWatchMetricsEnabled": true,
                "MetricName": "AWSManagedRulesKnownBadInputsRuleSet"
            }
        }
    ]'

The response includes the web ACL’s ARN under Summary.ARN. Note this ARN — you reference it in the distribution configuration in the next step, and again in the resourceArns list when you create the subscription.

Step 2: Create the distribution

Create a distribution that references the web ACL from Step 1. In the distribution configuration, set the WebACLId field to the web ACL ARN you noted previously. The following example creates a distribution from a configuration file.

aws cloudfront create-distribution \
    --distribution-config file://distribution-config.json

The response includes the distribution’s ARN under Distribution.ARN and its ID under Distribution.Id. Use the distribution ARN, together with the web ACL ARN from Step 1, in the resourceArns list when you create the subscription. For details about distribution configuration, see Create a distribution in the Amazon CloudFront Developer Guide.

Step 3: Create the subscription

Create the subscription, passing both the distribution ARN and the web ACL ARN in resourceArns. When you run this interactively and are ready to start billing, use IMMEDIATE approval mode to create and activate the subscription in a single step.

aws pricing-plan-manager create-subscription \
    --plan-family CloudFront \
    --plan-tier BUSINESS \
    --resource-arns \
        arn:aws:cloudfront::111122223333:distribution/EDFDVBD6EXAMPLE \
        arn:aws:wafv2:us-east-1:111122223333:global/webacl/my-plan-web-acl/a1b2c3d4-5678-90ab-cdef-EXAMPLE22222 \
    --approval-mode IMMEDIATE

The subscription is created with status ACTIVE, and billing begins immediately. Using IMMEDIATE requires both the pricingplanmanager:CreateSubscription and pricingplanmanager:ApprovePaidSubscription permissions.

For automated workflows—​such as deployment pipelines, agents, or service roles—​use MANUAL approval mode instead, so that a human authorizes billing in a separate step. For that flow, including guidance on separating create and approve permissions, see Subscribe and approve a paid plan and Two-phase subscription creation.

Recommended: Anti-DDoS managed rule group for Business and Premium

For BUSINESS and PREMIUM plans, we recommend adding the AWS WAF Anti-DDoS managed rule group (AWSManagedRulesAntiDDoSRuleSet) to your web ACL. This rule group identifies and blocks DDoS attacks by learning your application’s traffic patterns to distinguish attacks from legitimate surges. Advanced DDoS protection is included in the Business and Premium tiers. For more information, see AWS WAF Anti-DDoS rule group in the AWS WAF Developer Guide.

Add the following rule to the --rules array shown previously (adjust Priority so it doesn’t collide with your other rules):

{
    "Name": "AWS-AWSManagedRulesAntiDDoSRuleSet",
    "Priority": 3,
    "Statement": {
        "ManagedRuleGroupStatement": {
            "VendorName": "AWS",
            "Name": "AWSManagedRulesAntiDDoSRuleSet"
        }
    },
    "OverrideAction": { "None": {} },
    "VisibilityConfig": {
        "SampledRequestsEnabled": true,
        "CloudWatchMetricsEnabled": true,
        "MetricName": "AWSManagedRulesAntiDDoSRuleSet"
    }
}

Unsupported configurations

You can’t subscribe a distribution to a CloudFront plan if it uses certain features (for example, real-time logs, multi-tenant distributions, or staging distributions for continuous deployment). If the distribution uses an unsupported feature, CreateSubscription fails with a ValidationException. Disable or remove the unsupported feature before you subscribe. For the complete list of unsupported features and their alternatives, see Unsupported features in the Amazon CloudFront Developer Guide.

Error handling

The PricingPlanManager API returns the following error types. Handle these in your application to provide appropriate error recovery.

Handling concurrency conflicts

Because the PricingPlanManager API uses optimistic concurrency, your application should handle ConflictException gracefully. The recommended pattern is to retrieve the latest ETag and retry the operation:

SUBSCRIPTION_ARN="arn:aws:pricingplanmanager:us-east-1:111122223333:subscription/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111"

# Get the latest ETag
ETAG=$(aws pricing-plan-manager get-subscription \
    --arn "$SUBSCRIPTION_ARN" \
    --query 'eTag' \
    --output text)

# Retry the update with the fresh ETag
aws pricing-plan-manager update-subscription \
    --arn "$SUBSCRIPTION_ARN" \
    --if-match "$ETAG" \
    --plan-tier PREMIUM

Handling throttling

If you receive a ThrottlingException (HTTP 429), wait before retrying. Implement exponential backoff in your scripts by increasing the wait time between retries:

MAX_RETRIES=5
ATTEMPT=0

while [ $ATTEMPT -lt $MAX_RETRIES ]; do
    RESPONSE=$(aws pricing-plan-manager list-subscriptions --output json 2>&1) && break
    if echo "$RESPONSE" | grep -q "ThrottlingException"; then
        DELAY=$((2 ** ATTEMPT))
        echo "Throttled. Retrying in ${DELAY}s (attempt $((ATTEMPT+1))/${MAX_RETRIES})..."
        sleep $DELAY
        ATTEMPT=$((ATTEMPT + 1))
    else
        echo "Error: $RESPONSE"
        break
    fi
done