All Products
Search

This Product

    Object Storage Service:put-bucket-request-payment

    Document Center

    Object Storage Service:put-bucket-request-payment

    Last Updated:Feb 27, 2026

    Enables pay-by-requester for a bucket.

    Description

    The put-bucket-request-payment command configures pay-by-requester for the specified bucket. When pay-by-requester is enabled:

    • The requester pays for requests and traffic.

    • The bucket owner pays for data storage.

    • Anonymous access to the bucket is disabled.

    Usage notes

    • Permissions: An Alibaba Cloud account can enable pay-by-requester by default. To use a RAM user or Security Token Service (STS), you must have the oss:PutBucketRequestPayment permission. For more information, see Attach a custom policy to a RAM user.

    • Authentication: All requesters must provide authentication information. OSS uses this information to identify and charge the requester. If a requester uses a RAM user, the Alibaba Cloud account that owns the RAM user is charged for the requests and the generated traffic.

    • Request header: Requesters must include the x-oss-request-payer:requester header in POST, GET, or HEAD requests. This header indicates that requesters understand that they are charged for the requests and downloaded data. Otherwise, the requests cannot be authenticated. The bucket owner does not need to include this header. When the bucket owner accesses the bucket, the bucket owner is charged for the requests and the generated traffic.

    Command syntax

    ossutil api put-bucket-request-payment --bucket value --request-payment-configuration value [flags]

    Parameters

    ParameterTypeRequiredDescription
    --bucketstringYesThe name of the bucket.
    --request-payment-configurationstringYesThe pay-by-requester configuration in XML or JSON format. Use the file:// prefix to read from a file.

    --request-payment-configuration format

    XML:

    <RequestPaymentConfiguration>
  <Payer>string</Payer>
</RequestPaymentConfiguration>

    JSON:

    {
  "Payer": "string"
}

    Valid values for Payer:

    • BucketOwner: request and traffic fees are paid by the bucket owner.

    • Requester: request and traffic fees are paid by the requester.

    Note

    For global command-line options, see Global command-line options.

    Examples

    Enable pay-by-requester for a bucket named examplebucket.

    XML configuration file

    1. Create request-payment-configuration.xml:

         <?xml version="1.0" encoding="UTF-8"?>
   <RequestPaymentConfiguration>
     <Payer>Requester</Payer>
   </RequestPaymentConfiguration>

    2. Run the command:

         ossutil api put-bucket-request-payment --bucket examplebucket --request-payment-configuration file://request-payment-configuration.xml

    JSON configuration file

    1. Create request-payment-configuration.json:

         {
     "Payer": "Requester"
   }

    2. Run the command:

         ossutil api put-bucket-request-payment --bucket examplebucket --request-payment-configuration file://request-payment-configuration.json

    Inline JSON

    ossutil api put-bucket-request-payment --bucket examplebucket --request-payment-configuration "{\"Payer\":\"Requester\"}"

    Related API operation

    This command calls the PutBucketRequestPayment API operation.