Request Syntax URI Request Parameters Request Body Response Syntax Response Elements Errors See Also

UpdateSubscription

Changes the plan tier of an existing subscription.

Note

Upgrades take effect immediately. Downgrades are scheduled and the current tier remains unchanged until the end of the billing cycle (calendar month). You cannot update a subscription while a scheduled change is pending. To make a new change, first cancel the pending change using CancelSubscriptionChange.

This operation replaces the plan tier value. If you omit the optional usageLevel field, it is reset to the default.

Request Syntax


POST /v1/UpdateSubscription HTTP/1.1
If-Match: ifMatch
Content-type: application/json

{
   "arn": "string",
   "clientToken": "string",
   "planTier": "string",
   "usageLevel": "string"
}

URI Request Parameters

The request uses the following URI parameters.

ifMatch

The ETag value from a previous GetSubscription or ListSubscriptions response. This ensures you are updating the expected version of the subscription.

Required: Yes

Request Body

The request accepts the following data in JSON format.

arn

The ARN of the subscription to update.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 2048.

Required: Yes

planTier

The new tier level for the subscription.

Type: String

Required: Yes

clientToken

A unique, case-sensitive identifier that you provide to ensure the request is handled only once.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 64.

Required: No

usageLevel

The usage level within the plan tier. Specify DEFAULT for the base configuration. If omitted, the usage level is reset to the default.

Type: String

Required: No

Response Syntax


HTTP/1.1 200
ETag: eTag
Content-type: application/json

{
   "arn": "string",
   "createdAt": "string",
   "planFamily": "string",
   "planTier": "string",
   "resourceArns": [ "string" ],
   "scheduledChange": { 
      "changeType": "string",
      "effectiveDate": "string",
      "planTier": "string",
      "usageLevel": "string"
   },
   "status": "string",
   "statusReason": "string",
   "updatedAt": "string",
   "usageLevel": "string"
}

Response Elements

If the action is successful, the service sends back an HTTP 200 response.

The response returns the following HTTP headers.

eTag: The updated entity tag for concurrency control.

The following data is returned in JSON format by the service.

arn

The Amazon Resource Name (ARN) that uniquely identifies this subscription.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 2048.

createdAt

The date and time when the subscription was created, in ISO 8601 format.

Type: Timestamp

planFamily

The pricing plan family for the subscription, such as CloudFront.

Type: String

planTier

The current tier level of the pricing plan, such as FREE, PRO, BUSINESS, or PREMIUM.

Type: String

resourceArns

The ARNs of the Amazon resources covered by this subscription.

Type: Array of strings

Array Members: Minimum number of 1 item. Maximum number of 10 items.

status

The current status of the subscription. For the list of possible values, see the Status type.

Type: String

Valid Values: PENDING_APPROVAL | ACTIVE | SYNC_IN_PROGRESS | FAILED

updatedAt

The date and time when the subscription was last modified, in ISO 8601 format.

Type: Timestamp

scheduledChange

A pending change that will take effect at the end of the current billing period. This field is present only when a downgrade or cancellation is scheduled.

Type: ScheduledChange object

statusReason

A human-readable explanation of the current status, present when additional context is available.

Type: String

usageLevel

The usage level within the plan tier. When present, indicates a specific capacity configuration beyond the base tier.

Type: String

Errors

For information about the errors that are common to all actions, see Common Error Types.

AccessDeniedException

You do not have the required permissions to perform this operation. Verify that your IAM policy grants access to this action.

HTTP Status Code: 403

ConflictException

The request conflicts with the current state of the resource. This typically occurs when the ETag value in the If-Match header does not match the current version of the subscription. Retrieve the latest version and retry.

resourceId: The identifier of the resource that has a conflicting state.

HTTP Status Code: 409

InternalServerException

An unexpected error occurred on the server. Retry the request.

HTTP Status Code: 500

ResourceNotFoundException

The specified subscription was not found. Verify that the ARN is correct and that the subscription belongs to your account.

resourceId: The identifier of the resource that was not found.

HTTP Status Code: 404

ServiceQuotaExceededException

The request would exceed a service limit. You have reached the maximum number of subscriptions allowed for your account.

HTTP Status Code: 402

ThrottlingException

The request rate exceeds the allowed limit. Wait briefly and retry the request.

HTTP Status Code: 429

ValidationException

The request failed a business rule validation. For example, the specified resource might already be associated with another subscription, or the subscription might not be in the required state for this operation.

resourceId: The identifier of the resource that failed validation.

HTTP Status Code: 400