Amazon Simple Storage Service
API Reference (API Version 2006-03-01)

PUT Bucket tagging


This implementation of the PUT operation uses the tagging subresource to add a set of tags to an existing bucket.

Use tags to organize your AWS bill to reflect your own cost structure. To do this, sign up to get your AWS account bill with tag key values included. Then, to see the cost of combined resources, organize your billing information according to resources with the same tag key values. For example, you can tag several resources with a specific application name, and then organize your billing information to see the total cost of that application across several services. For more information, see Cost Allocation and Tagging in About AWS Billing and Cost Management.


  • If you use the PUT Bucket tagging to add a set of tags to an existing bucket, any existing tag set will be overwritten.

  • Within a bucket, if you add a tag that has the same key as an existing tag, the new value overwrites the old value. For more information, see Using Cost Allocation in Amazon S3 Bucket Tags in AWS Billing and Cost Management.

To use this operation, you must have permissions to perform the s3:PutBucketTagging action. The bucket owner has this permission by default and can grant this permission to others. For more information about permissions, see Permissions Related to Bucket Subresource Operations and Managing Access Permissions to Your Amazon S3 Resources in the Amazon Simple Storage Service Developer Guide.



The following request shows the syntax for sending tagging information in the request body.

PUT /?tagging HTTP/1.1 Host: Date: date Authorization: authorization string (see Authenticating Requests (AWS Signature Version 4)) <Tagging> <TagSet> <Tag> <Key>Tag Name</Key> <Value>Tag Value</Value> </Tag> </TagSet> </Tagging>

Request Parameters

This implementation of the operation does not use request parameters.

Request Headers

Content-MD5 will be a required header for this operation.

Request Elements

Name Description Required

Container for the TagSet and Tag elements.

Type: String

Ancestors: None


Container for a set of tags

Type: Container

Ancestors: Tagging


Container for tag information.

Type: Container

Ancestors: TagSet


Name of the tag.

Type: String

Ancestors: Tag


Value of the tag.

Type: String

Ancestors: Tag



Response Headers

The operation returns response headers that are common to most responses. For more information, see Common Response Headers.

Response Elements

This operation does not return response elements.

Special Errors

  • InvalidTagError - The tag provided was not a valid tag. This error can occur if the tag did not pass input validation. For information about tag restrictions, see User-Defined Tag Restrictions and AWS-Generated Cost Allocation Tag Restrictions in the AWS Billing and Cost Management User Guide.

  • MalformedXMLError - The XML provided does not match the schema.

  • OperationAbortedError - A conflicting conditional operation is currently in progress against this resource. Please try again.

  • InternalError - The service was unable to apply the provided tag to the bucket.


Sample Request: Add tag set to a bucket

The following request adds a tag set to the existing examplebucket bucket.

PUT ?tagging HTTP/1.1 Host: Content-Length: 1660 x-amz-date: Thu, 12 Apr 2012 20:04:21 GMT Authorization: authorization string <Tagging> <TagSet> <Tag> <Key>Project</Key> <Value>Project One</Value> </Tag> <Tag> <Key>User</Key> <Value>jsmith</Value> </Tag> </TagSet> </Tagging>

Sample Response

HTTP/1.1 204 No Content x-amz-id-2: YgIPIfBiKa2bj0KMgUAdQkf3ShJTOOpXUueF6QKo x-amz-request-id: 236A8905248E5A01 Date: Wed, 01 Oct 2012 12:00:00 GMT