This is the new *CloudFormation Template Reference Guide*. Please update your bookmarks and links. For help getting started with CloudFormation, see the [AWS CloudFormation User Guide](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/Welcome.html).

# AWS::ApiGateway::UsagePlan
<a name="aws-resource-apigateway-usageplan"></a>

The `AWS::ApiGateway::UsagePlan` resource creates a usage plan for deployed APIs. A usage plan sets a target for the throttling and quota limits on individual client API keys. For more information, see [Creating and Using API Usage Plans in Amazon API Gateway](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-api-usage-plans.html) in the *API Gateway Developer Guide*.

In some cases clients can exceed the targets that you set. Don’t rely on usage plans to control costs. Consider using [AWS Budgets](https://docs.aws.amazon.com/cost-management/latest/userguide/budgets-managing-costs.html) to monitor costs and [AWS WAF](https://docs.aws.amazon.com/waf/latest/developerguide/waf-chapter.html) to manage API requests.

## Syntax
<a name="aws-resource-apigateway-usageplan-syntax"></a>

To declare this entity in your CloudFormation template, use the following syntax:

### JSON
<a name="aws-resource-apigateway-usageplan-syntax.json"></a>

```
{
  "Type" : "AWS::ApiGateway::UsagePlan",
  "Properties" : {
      "[ApiStages](#cfn-apigateway-usageplan-apistages)" : [ ApiStage, ... ],
      "[Description](#cfn-apigateway-usageplan-description)" : String,
      "[Quota](#cfn-apigateway-usageplan-quota)" : QuotaSettings,
      "[Tags](#cfn-apigateway-usageplan-tags)" : [ Tag, ... ],
      "[Throttle](#cfn-apigateway-usageplan-throttle)" : ThrottleSettings,
      "[UsagePlanName](#cfn-apigateway-usageplan-usageplanname)" : String
    }
}
```

### YAML
<a name="aws-resource-apigateway-usageplan-syntax.yaml"></a>

```
Type: AWS::ApiGateway::UsagePlan
Properties:
  [ApiStages](#cfn-apigateway-usageplan-apistages): 
    - ApiStage
  [Description](#cfn-apigateway-usageplan-description): String
  [Quota](#cfn-apigateway-usageplan-quota): 
    QuotaSettings
  [Tags](#cfn-apigateway-usageplan-tags): 
    - Tag
  [Throttle](#cfn-apigateway-usageplan-throttle): 
    ThrottleSettings
  [UsagePlanName](#cfn-apigateway-usageplan-usageplanname): String
```

## Properties
<a name="aws-resource-apigateway-usageplan-properties"></a>

`ApiStages`  <a name="cfn-apigateway-usageplan-apistages"></a>
The associated API stages of a usage plan.  
*Required*: No  
*Type*: Array of [ApiStage](aws-properties-apigateway-usageplan-apistage.md)  
*Update requires*: [No interruption](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-updating-stacks-update-behaviors.html#update-no-interrupt)

`Description`  <a name="cfn-apigateway-usageplan-description"></a>
The description of a usage plan.  
*Required*: No  
*Type*: String  
*Update requires*: [No interruption](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-updating-stacks-update-behaviors.html#update-no-interrupt)

`Quota`  <a name="cfn-apigateway-usageplan-quota"></a>
The target maximum number of permitted requests per a given unit time interval.  
*Required*: No  
*Type*: [QuotaSettings](aws-properties-apigateway-usageplan-quotasettings.md)  
*Update requires*: [No interruption](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-updating-stacks-update-behaviors.html#update-no-interrupt)

`Tags`  <a name="cfn-apigateway-usageplan-tags"></a>
The collection of tags. Each tag element is associated with a given resource.  
*Required*: No  
*Type*: Array of [Tag](aws-properties-apigateway-usageplan-tag.md)  
*Update requires*: [No interruption](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-updating-stacks-update-behaviors.html#update-no-interrupt)

`Throttle`  <a name="cfn-apigateway-usageplan-throttle"></a>
A map containing method level throttling information for API stage in a usage plan.  
*Required*: No  
*Type*: [ThrottleSettings](aws-properties-apigateway-usageplan-throttlesettings.md)  
*Update requires*: [No interruption](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-updating-stacks-update-behaviors.html#update-no-interrupt)

`UsagePlanName`  <a name="cfn-apigateway-usageplan-usageplanname"></a>
The name of a usage plan.  
*Required*: No  
*Type*: String  
*Update requires*: [No interruption](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-updating-stacks-update-behaviors.html#update-no-interrupt)

## Return values
<a name="aws-resource-apigateway-usageplan-return-values"></a>

### Ref
<a name="aws-resource-apigateway-usageplan-return-values-ref"></a>

When you pass the logical ID of this resource to the intrinsic `Ref` function, `Ref` returns the usage plan ID, such as `abc123`.

For more information about using the `Ref` function, see [https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/intrinsic-function-reference-ref.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/intrinsic-function-reference-ref.html).

### Fn::GetAtt
<a name="aws-resource-apigateway-usageplan-return-values-fn--getatt"></a>

The `Fn::GetAtt` intrinsic function returns a value for a specified attribute of this type. The following are the available attributes and sample return values.

For more information about using the `Fn::GetAtt` intrinsic function, see [https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/intrinsic-function-reference-getatt.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/intrinsic-function-reference-getatt.html).

#### 
<a name="aws-resource-apigateway-usageplan-return-values-fn--getatt-fn--getatt"></a>

`Id`  <a name="Id-fn::getatt"></a>
The ID for the usage plan. For example: `abc123`.

## Examples
<a name="aws-resource-apigateway-usageplan--examples"></a>



### Create usage plan
<a name="aws-resource-apigateway-usageplan--examples--Create_usage_plan"></a>

The following examples create a usage plan for the Prod API stage, with a quota of 5000 requests per month and a rate limit of 100 requests per second.

#### JSON
<a name="aws-resource-apigateway-usageplan--examples--Create_usage_plan--json"></a>

```
{
    "usagePlan": {
        "Type": "AWS::ApiGateway::UsagePlan",
        "Properties": {
            "ApiStages": [
                {
                    "ApiId": {
                        "Ref": "MyRestApi"
                    },
                    "Stage": {
                        "Ref": "Prod"
                    }
                }
            ],
            "Description": "Customer ABC's usage plan",
            "Quota": {
                "Limit": 5000,
                "Period": "MONTH"
            },
            "Throttle": {
                "BurstLimit": 200,
                "RateLimit": 100
            },
            "UsagePlanName": "Plan_ABC"
        }
    }
}
```

#### YAML
<a name="aws-resource-apigateway-usageplan--examples--Create_usage_plan--yaml"></a>

```
usagePlan:
  Type: 'AWS::ApiGateway::UsagePlan'
  Properties:
    ApiStages:
      - ApiId: !Ref MyRestApi
        Stage: !Ref Prod
    Description: Customer ABC's usage plan
    Quota:
      Limit: 5000
      Period: MONTH
    Throttle:
      BurstLimit: 200
      RateLimit: 100
    UsagePlanName: Plan_ABC
```

## See also
<a name="aws-resource-apigateway-usageplan--seealso"></a>
+ [usageplan:create](https://docs.aws.amazon.com/apigateway/latest/api/API_CreateUsagePlan.html) in the *Amazon API Gateway REST API Reference*



# AWS::ApiGateway::UsagePlan ApiStage
<a name="aws-properties-apigateway-usageplan-apistage"></a>

API stage name of the associated API stage in a usage plan.

## Syntax
<a name="aws-properties-apigateway-usageplan-apistage-syntax"></a>

To declare this entity in your CloudFormation template, use the following syntax:

### JSON
<a name="aws-properties-apigateway-usageplan-apistage-syntax.json"></a>

```
{
  "[ApiId](#cfn-apigateway-usageplan-apistage-apiid)" : String,
  "[Stage](#cfn-apigateway-usageplan-apistage-stage)" : String,
  "[Throttle](#cfn-apigateway-usageplan-apistage-throttle)" : {Key: Value, ...}
}
```

### YAML
<a name="aws-properties-apigateway-usageplan-apistage-syntax.yaml"></a>

```
  [ApiId](#cfn-apigateway-usageplan-apistage-apiid): String
  [Stage](#cfn-apigateway-usageplan-apistage-stage): String
  [Throttle](#cfn-apigateway-usageplan-apistage-throttle): 
    Key: Value
```

## Properties
<a name="aws-properties-apigateway-usageplan-apistage-properties"></a>

`ApiId`  <a name="cfn-apigateway-usageplan-apistage-apiid"></a>
API Id of the associated API stage in a usage plan.  
*Required*: No  
*Type*: String  
*Update requires*: [No interruption](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-updating-stacks-update-behaviors.html#update-no-interrupt)

`Stage`  <a name="cfn-apigateway-usageplan-apistage-stage"></a>
API stage name of the associated API stage in a usage plan.  
*Required*: No  
*Type*: String  
*Update requires*: [No interruption](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-updating-stacks-update-behaviors.html#update-no-interrupt)

`Throttle`  <a name="cfn-apigateway-usageplan-apistage-throttle"></a>
Map containing method level throttling information for API stage in a usage plan.  
*Required*: No  
*Type*: Object of [ThrottleSettings](aws-properties-apigateway-usageplan-throttlesettings.md)  
*Update requires*: [No interruption](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-updating-stacks-update-behaviors.html#update-no-interrupt)

## See also
<a name="aws-properties-apigateway-usageplan-apistage--seealso"></a>
+ [UsagePlan](https://docs.aws.amazon.com/apigateway/latest/api/API_UsagePlan.html) in the *Amazon API Gateway REST API Reference*



# AWS::ApiGateway::UsagePlan QuotaSettings
<a name="aws-properties-apigateway-usageplan-quotasettings"></a>

`QuotaSettings` is a property of the [AWS::ApiGateway::UsagePlan](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-usageplan.html) resource that specifies a target for the maximum number of requests users can make to your REST APIs.

In some cases clients can exceed the targets that you set. Don’t rely on usage plans to control costs. Consider using [AWS Budgets](https://docs.aws.amazon.com/cost-management/latest/userguide/budgets-managing-costs.html) to monitor costs and [AWS WAF](https://docs.aws.amazon.com/waf/latest/developerguide/waf-chapter.html) to manage API requests.

## Syntax
<a name="aws-properties-apigateway-usageplan-quotasettings-syntax"></a>

To declare this entity in your CloudFormation template, use the following syntax:

### JSON
<a name="aws-properties-apigateway-usageplan-quotasettings-syntax.json"></a>

```
{
  "[Limit](#cfn-apigateway-usageplan-quotasettings-limit)" : Integer,
  "[Offset](#cfn-apigateway-usageplan-quotasettings-offset)" : Integer,
  "[Period](#cfn-apigateway-usageplan-quotasettings-period)" : String
}
```

### YAML
<a name="aws-properties-apigateway-usageplan-quotasettings-syntax.yaml"></a>

```
  [Limit](#cfn-apigateway-usageplan-quotasettings-limit): Integer
  [Offset](#cfn-apigateway-usageplan-quotasettings-offset): Integer
  [Period](#cfn-apigateway-usageplan-quotasettings-period): String
```

## Properties
<a name="aws-properties-apigateway-usageplan-quotasettings-properties"></a>

`Limit`  <a name="cfn-apigateway-usageplan-quotasettings-limit"></a>
The target maximum number of requests that can be made in a given time period.  
*Required*: No  
*Type*: Integer  
*Minimum*: `0`  
*Update requires*: [No interruption](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-updating-stacks-update-behaviors.html#update-no-interrupt)

`Offset`  <a name="cfn-apigateway-usageplan-quotasettings-offset"></a>
The number of requests subtracted from the given limit in the initial time period.  
*Required*: No  
*Type*: Integer  
*Minimum*: `0`  
*Update requires*: [No interruption](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-updating-stacks-update-behaviors.html#update-no-interrupt)

`Period`  <a name="cfn-apigateway-usageplan-quotasettings-period"></a>
The time period in which the limit applies. Valid values are "DAY", "WEEK" or "MONTH".  
*Required*: No  
*Type*: String  
*Allowed values*: `DAY | WEEK | MONTH`  
*Update requires*: [No interruption](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-updating-stacks-update-behaviors.html#update-no-interrupt)

## See also
<a name="aws-properties-apigateway-usageplan-quotasettings--seealso"></a>
+ [UsagePlan](https://docs.aws.amazon.com/apigateway/latest/api/API_UsagePlan.html) in the *Amazon API Gateway REST API Reference*



# AWS::ApiGateway::UsagePlan Tag
<a name="aws-properties-apigateway-usageplan-tag"></a>

An array of key-value pairs to apply to this resource.

For more information, see [Tag](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-resource-tags.html).

## Syntax
<a name="aws-properties-apigateway-usageplan-tag-syntax"></a>

To declare this entity in your CloudFormation template, use the following syntax:

### JSON
<a name="aws-properties-apigateway-usageplan-tag-syntax.json"></a>

```
{
  "[Key](#cfn-apigateway-usageplan-tag-key)" : String,
  "[Value](#cfn-apigateway-usageplan-tag-value)" : String
}
```

### YAML
<a name="aws-properties-apigateway-usageplan-tag-syntax.yaml"></a>

```
  [Key](#cfn-apigateway-usageplan-tag-key): String
  [Value](#cfn-apigateway-usageplan-tag-value): String
```

## Properties
<a name="aws-properties-apigateway-usageplan-tag-properties"></a>

`Key`  <a name="cfn-apigateway-usageplan-tag-key"></a>
A string you can use to assign a value. The combination of tag keys and values can help you organize and categorize your resources.  
*Required*: Yes  
*Type*: String  
*Minimum*: `1`  
*Maximum*: `128`  
*Update requires*: [No interruption](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-updating-stacks-update-behaviors.html#update-no-interrupt)

`Value`  <a name="cfn-apigateway-usageplan-tag-value"></a>
The value for the specified tag key.  
*Required*: Yes  
*Type*: String  
*Minimum*: `0`  
*Maximum*: `256`  
*Update requires*: [No interruption](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-updating-stacks-update-behaviors.html#update-no-interrupt)

# AWS::ApiGateway::UsagePlan ThrottleSettings
<a name="aws-properties-apigateway-usageplan-throttlesettings"></a>

`ThrottleSettings` is a property of the [AWS::ApiGateway::UsagePlan](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-usageplan.html) resource that specifies the overall request rate (average requests per second) and burst capacity when users call your REST APIs.

## Syntax
<a name="aws-properties-apigateway-usageplan-throttlesettings-syntax"></a>

To declare this entity in your CloudFormation template, use the following syntax:

### JSON
<a name="aws-properties-apigateway-usageplan-throttlesettings-syntax.json"></a>

```
{
  "[BurstLimit](#cfn-apigateway-usageplan-throttlesettings-burstlimit)" : Integer,
  "[RateLimit](#cfn-apigateway-usageplan-throttlesettings-ratelimit)" : Number
}
```

### YAML
<a name="aws-properties-apigateway-usageplan-throttlesettings-syntax.yaml"></a>

```
  [BurstLimit](#cfn-apigateway-usageplan-throttlesettings-burstlimit): Integer
  [RateLimit](#cfn-apigateway-usageplan-throttlesettings-ratelimit): Number
```

## Properties
<a name="aws-properties-apigateway-usageplan-throttlesettings-properties"></a>

`BurstLimit`  <a name="cfn-apigateway-usageplan-throttlesettings-burstlimit"></a>
The API target request burst rate limit. This allows more requests through for a period of time than the target rate limit.  
*Required*: No  
*Type*: Integer  
*Minimum*: `0`  
*Update requires*: [No interruption](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-updating-stacks-update-behaviors.html#update-no-interrupt)

`RateLimit`  <a name="cfn-apigateway-usageplan-throttlesettings-ratelimit"></a>
The API target request rate limit.  
*Required*: No  
*Type*: Number  
*Minimum*: `0`  
*Update requires*: [No interruption](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-updating-stacks-update-behaviors.html#update-no-interrupt)

## See also
<a name="aws-properties-apigateway-usageplan-throttlesettings--seealso"></a>
+ [UsagePlan](https://docs.aws.amazon.com/apigateway/latest/api/API_UsagePlan.html) in the *Amazon API Gateway REST API Reference*