All Products
Search

This Product

    Object Storage Service:PutObjectRetention

    Document Center

    Object Storage Service:PutObjectRetention

    Last Updated:Apr 09, 2026

    Sets an object retention policy, which includes a retention mode and a retain until date, for a specified object version. An object-level retention policy takes precedence over the default ObjectWorm retention policy that is configured for the bucket.

    Usage notes

    Important

    This feature is currently available by invitation only. To request access, contact technical support. This feature is available only in the China (Hangzhou), China (Chengdu), China (Shenzhen), China (Guangzhou), China (Qingdao), China (Beijing), China (Hohhot), China (Heyuan), China (Hong Kong), Germany (Frankfurt), Japan (Tokyo), South Korea (Seoul), Singapore, Malaysia (Kuala Lumpur), Indonesia (Jakarta), Philippines (Manila), Thailand (Bangkok), Saudi Arabia (Riyadh), and UAE (Dubai) regions.

    • Before you call this operation, you must enable the object-level retention policy (ObjectWorm) for the bucket by calling the PutBucketObjectWormConfiguration operation.

    • To call this operation, you must have the oss:PutObjectRetention permission.

    • In compliance mode, the RetainUntilDate value can only be extended and cannot be shortened. If you set a date that is earlier than the current retain until date, an error is returned.

    • An object-level retention policy set by this operation overrides the default ObjectWorm policy of the bucket.

    • You cannot set an object retention policy on an appendable object.

    • The RetainUntilDate value must be in the future.

    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 sets an object retention policy.

    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.