Call PutObjectRetention to set an object retention policy - Object Storage Service

Sets a retention policy for a specific object version to prevent deletion or modification until a specified date. This operation is essential for compliance scenarios where data immutability is required. Object-level retention policies override the bucket-level retention policy, allowing granular control over individual objects.

Usage notes

Important

This feature is currently available by invitation only. To request access, contact technical support.

Before calling this operation, you must enable ObjectWorm (Write Once Read Many) for the bucket by calling the PutBucketObjectWormConfiguration operation. If ObjectWorm is not enabled, the request fails with an InvalidRequest error.
To call this operation, you must have the oss:PutObjectRetention permission. This permission can be granted through RAM policies or bucket policies.
In compliance mode, the RetainUntilDate value can only be extended, not shortened. Attempting to set an earlier date than the current retention date returns an AccessDenied error. This ensures data immutability for compliance requirements.
Object-level retention policies set by this operation override the bucket-level retention policy. This allows you to apply stricter retention requirements to specific objects while maintaining a default policy for the bucket.
Appendable objects do not support retention policies. If you attempt to set a retention policy on an appendable object, the request fails.
The RetainUntilDate value must be a future date. Past or current dates are rejected.
Retention policies work with versioning. If you do not specify a versionId, the policy applies to the current (latest) version of the object. To protect specific versions, include the version ID in your request.
During the retention period, protected object versions cannot be deleted, overwritten, or have their retention shortened—even by the root account. Plan retention periods carefully, as they cannot be undone in compliance mode.

Request syntax

PUT /ObjectName?retention HTTP/1.1
Content-MD5: ContentMD5
Content-Length: ContentLength
Content-Type: application/xml
Host: BucketName.oss-cn-hangzhou.aliyuncs.com
Date: GMT Date
Authorization: SignatureValue

Request parameters

Parameter	Type	Required	Example	Description
retention	N/A	Yes	N/A	Specifies that the operation configures an object retention policy. This is a required query parameter to indicate the retention operation.
versionId	String	No	CAEQNhiBgMDJgZCA0BYiIDc4MGZj****	The version ID of the object. If you do not specify this parameter, the operation applies to the latest version of the object.

Request headers

Header	Type	Required	Example	Description
Content-MD5	String	Yes	B2M2Y8AsgTpgAmY7PhC****	The MD5 hash of the request body. This header is used for data integrity verification.

Request body elements

Element	Type	Required	Example	Description
Retention	Container	Yes	N/A	The container for the object retention policy. Parent: None Children: Mode, RetainUntilDate
Mode	String	Yes	COMPLIANCE	The retention mode of the object. Valid value: COMPLIANCE: During the retention period, no user, including the root user, can delete or overwrite the protected object version. The retention period cannot be shortened. Parent: Retention
RetainUntilDate	String	Yes	2026-10-11T00:00:00.000Z	The retain until date of the object. The value is a date in the ISO 8601 format. Before this date, the object version cannot be deleted or overwritten. The specified date must be in the future. In compliance mode, this date can only be extended and cannot be shortened. Parent: Retention

Response headers

Header	Example	Description
x-oss-version-id	CAEQNhiBgMDJgZCA0BYiIDc4MGZj****	The version ID of the object that the retention policy applies to.

Examples

Example 1: Set a compliance mode retention policy

Sample request

PUT /exampleobject?retention&versionId=CAEQNhiBgMDJgZCA0BYiIDc4MGZj**** HTTP/1.1
Date: Thu, 17 Mar 2026 11:18:32 GMT
Content-MD5: B2M2Y8AsgTpgAmY7PhC****
Content-Type: application/xml
Content-Length: 162
Host: examplebucket.oss-cn-hangzhou.aliyuncs.com
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20260317/cn-hangzhou/oss/aliyun_v4_request,Signature=****

<Retention>
  <Mode>COMPLIANCE</Mode>
  <RetainUntilDate>2026-10-11T00:00:00.000Z</RetainUntilDate>
</Retention>

Sample response

HTTP/1.1 200 OK
x-oss-request-id: 5374A2880232A65C2300****
x-oss-version-id: CAEQNhiBgMDJgZCA0BYiIDc4MGZj****
Date: Thu, 17 Mar 2026 11:18:32 GMT
Content-Length: 0
Server: AliyunOSS

Example 2: Extend the retain until date

The following example extends the retain until date of an object to March 11, 2027. In compliance mode, the retain until date can only be extended and cannot be shortened.

Sample request

PUT /exampleobject?retention&versionId=CAEQNhiBgMDJgZCA0BYiIDc4MGZj**** HTTP/1.1
Date: Thu, 17 Mar 2026 11:18:32 GMT
Content-MD5: D3N3Z9CtiVqhCnZ9RjE****
Content-Type: application/xml
Content-Length: 162
Host: examplebucket.oss-cn-hangzhou.aliyuncs.com
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20260317/cn-hangzhou/oss/aliyun_v4_request,Signature=****

<Retention>
  <Mode>COMPLIANCE</Mode>
  <RetainUntilDate>2027-03-11T00:00:00.000Z</RetainUntilDate>
</Retention>

Sample response

HTTP/1.1 200 OK
x-oss-request-id: 6485B3990232A65C3400****
x-oss-version-id: CAEQNhiBgMDJgZCA0BYiIDc4MGZj****
Date: Thu, 17 Mar 2026 11:20:15 GMT
Content-Length: 0
Server: AliyunOSS

Error codes

Error code	HTTP status code	Description
InvalidRequest	400	ObjectWorm is not enabled for the bucket. You cannot set an object retention policy.
AccessDenied	403	You cannot shorten the retain until date in compliance mode.