After pay-by-requester mode is enabled for a bucket in Alibaba Cloud OSS, the requester instead of the bucket owner pays the cost of requests and traffic. The bucket owner always pays the cost of storing data. You can enable this feature to share data without having to pay for all requests and traffic by yourself.

Request methods

  • Access from anonymous users is not allowed

    If you enable pay-by-requester mode for a bucket, anonymous users are not allowed to access the bucket. Requesters must provide authentication information so that OSS can identify and charge them, but not the bucket owner, for requests and traffic.

    If requesters assume the RAM role of an Alibaba Cloud account to request data, OSS charges this Alibaba Cloud account for such requests and traffic.

  • Requesters must include the x-oss-request-payer request header

    If you enable pay-by-requester mode for a bucket, requesters must include the x-oss-request-payer:requester request header in a PUT, POST, GET, or HEAD request. This field indicates that requesters understand that their requests and data downloads incur fees. Otherwise, requests cannot pass authentication.

    Bucket owners do not need to include the x-oss-request-payer request header when accessing their own buckets. In this case, bucket owners are requesters who pay for such requests and traffic.

For more information about pay-by-requester mode, see Enable pay-by-requester in the OSS Developer Guide.

Configure the pay-by-requester mode

The following code provides an example of how to enable pay-by-requester mode:
// This example uses China (Hangzhou) as the endpoint. Specify the actual endpoint based on your requirements.
String endpoint = "http://oss-cn-hangzhou.aliyuncs.com";
// Security risks may arise if you log on with the AccessKey pair of an Alibaba Cloud account because the account has permissions on all API operations in OSS. We recommend that you log on with a RAM user account to call API operations or perform routine operations and maintenance. To create a RAM user account, log on to https://ram.console.aliyun.com.
String accessKeyId = "<yourAccessKeyId>";
String accessKeySecret = "<yourAccessKeySecret>";

// Create an OSSClient instance.
OSS ossClient = new OSSClientBuilder().build(endpoint, accessKeyId, accessKeySecret);

// Enable requester payment mode.
Payer payer = Payer.Requester;
ossClient.setBucketRequestPayment(bucketName, payer);

// Close your OSSClient.
ossClient.shutdown();
const OSS = require('ali-oss')

const client = new OSS({
  region: '<Your region>',
  // Security risks may arise if you use the AccessKey pair of an Alibaba Cloud account to log on to OSS, because the account has permissions on all API operations. We recommend that you use a RAM user to call API operations or perform routine operations and maintenance. To create a RAM user, log on to https://ram.console.aliyun.com.
  accessKeyId: '<Your AccessKeyId>',
  accessKeySecret: '<Your AccessKeySecret>',
});

async function setBucketRequestPayment(bucket, Payer) {
  try {
    // Set bucket to the name of the bucket to configure the pay-by-requester mode.
    // Set Payer to Requester or BucketOwner.
    // If Payer is set to Requester, the pay-by-requester mode is enabled for the bucket. The requester is charged for the traffic and request fees that are generated when reading data in the bucket.
    // If Payer is set to BucketOwner, the pay-by-requester mode is disabled for the bucket. This is the default configuration for the bucket. In this case, the bucket owner is charged for the request fees.
    let result = await client.putBucketRequestPayment(bucket, Payer);
    console.log(result);
  } catch (e) {
    console.log(e);
  }
}

setBucketRequestPayment('bucketName', 'Requester')

For more information about how to configure the pay-by-requester mode for a bucket, see PutBucketRequestPayment.

Query pay-by-requester configurations

The following code provides an example of how to obtain pay-by-requester configurations:
// This example uses China (Hangzhou) as the endpoint. Specify the actual endpoint based on your requirements.
String endpoint = "http://oss-cn-hangzhou.aliyuncs.com";
// Security risks may arise if you log on with the AccessKey pair of an Alibaba Cloud account because the account has permissions on all API operations in OSS. We recommend that you log on with a RAM user account to call API operations or perform routine operations and maintenance. To create a RAM user account, log on to https://ram.console.aliyun.com.
String accessKeyId = "<yourAccessKeyId>";
String accessKeySecret = "<yourAccessKeySecret>";

// Create an OSSClient instance.
OSS ossClient = new OSSClientBuilder().build(endpoint, accessKeyId, accessKeySecret);

// Obtain pay-by-requester configurations.
GetBucketRequestPaymentResult result = ossClient.getBucketRequestPayment(bucketName);
System.out.println("Payer:" + result.getPayer());

// Close your OSSClient.
ossClient.shutdown();
const OSS = require('ali-oss')

const client = new OSS({
  region: '<Your region>',
  // Security risks may arise if you use the AccessKey pair of an Alibaba Cloud account to log on to OSS, because the account has permissions on all API operations. We recommend that you use a RAM user to call API operations or perform routine operations and maintenance. To create a RAM user, log on to https://ram.console.aliyun.com.
  accessKeyId: '<Your AccessKeyId>',
  accessKeySecret: '<Your AccessKeySecret>',
});

async function getBucketRequestPayment(bucket) {
  try {
    // Query the pay-by-requester configurations.
    let result = await client.getBucketRequestPayment(bucket);
    console.log(result.payer);
  } catch (e) {
    console.log(e);
  }
}

getBucketRequestPayment('bucketName')

For more information about how to query the pay-by-requester configurations of a bucket, see GetBucketRequestPayment.

Specify a third party to pay for access to objects

The following code provides an example on how to specify a third party to pay for access to objects when you call the PutObject, GetObject, and DeleteObject operations:

const OSS = require('ali-oss')
const bucket = 'bucket-name'
const payer = 'Requester'

const client = new OSS({
  region: '<Your region>',
  // Security risks may arise if you log on with the AccessKey pair of an Alibaba Cloud account because the account has permissions on all API operations in OSS. We recommend that you use a RAM user to call API operations or perform routine operations and maintenance. To create a RAM user, log on to https://ram.console.aliyun.com.
  accessKeyId: '<Your AccessKeyId>',
  accessKeySecret: '<Your AccessKeySecret>',
  bucket: bucket
});


async function put() {
  await client.putBucketRequestPayment(bucket, payer)

  // Specify the payer when you call the PutObject operation.
  await client.put('fileName', 'fileContent', {
    headers: {
      'x-oss-request-payer': 'requester'
    }
  })
}

async function get () {
  await client.putBucketRequestPayment(bucket, payer)

  // Specify the payer when you call the GetObject operation.
  await client.get('fileName', {
    headers: {
      'x-oss-request-payer': 'requester'
    }
  })
}

async function del() {
  await client.putBucketRequestPayment(bucket, payer)

  // Specify the payer when you call the DeleteObject operation.
  await client.delete('fileName', {
    headers: {
      'x-oss-request-payer': 'requester'
    }
  })
}