The [amazon_s3] shortcode links a product download straight to a file that’s already in one of your buckets, without uploading anything from your store. Use it in a downloadable file’s File URL, and customers who bought the product download that file through a signed link, just like an offloaded file.
It works with Amazon S3, Cloudflare R2 and the experimental providers, and with any bucket your access keys can read.
When you’d use this
- Your files are already in a bucket, or you upload them with the AWS console, the Cloudflare dashboard or another tool.
- A file is larger than automatic offloading can upload (5 GB on Amazon S3).
- You keep files in more than one bucket. Automatic offloading uses one bucket; shortcodes can point at any of them.
- You’d rather not keep a copy of the file on your web server.
How to use it
1. Upload the file to your bucket
Upload the file with your provider’s console or a tool such as the AWS CLI or rclone, and keep it private. Note its object name: the path inside the bucket, such as courses/module-1.zip, without the bucket name or https://.
Simple object names avoid surprises: lowercase letters, numbers, hyphens and slashes for folders.
2. Add the file with the shortcode generator
- Edit the product, tick Downloadable (or open a downloadable variation), and find Downloadable files.
- Click Add S3 file shortcode, next to Add File.
- In the Add S3 file window, fill in:
- Bucket name: leave it empty to use your Default bucket.
- S3 region: leave it at Default, or pick the bucket’s region (see How the bucket and region are chosen).
- Object name: the object name from step 1. Don’t paste the file’s URL here.
- The shortcode builds itself at the top of the window as you type. Click Add file to add a row with the shortcode as its File URL and a file name based on the object name, or Copy shortcode to paste it somewhere yourself.
- Edit the file name if you like, then click Update.
The row’s S3 status shows Shortcode. To change it later, click Choose file on that row, which reopens the window as Edit S3 file, and click Update file.
3. Test the download
Download the file from a test order. If it doesn’t download, see Common issues below.
Write the shortcode by hand
You can also type the shortcode into a File URL field:
[amazon_s3 object="courses/module-1.zip" bucket="my-store-files" region="eu-west-1"]| Attribute | Required | What it does |
|---|---|---|
object | Yes | The object name in the bucket. |
bucket | Only without a Default bucket | The bucket to read from. |
region | Recommended for buckets other than the Default bucket | The bucket’s AWS region code, such as us-east-1. Ignored for Cloudflare R2. |
content_disposition | No | attachment makes browsers download the file, inline lets them display it. Overrides the Download behavior setting for this file. |
Put each value in double quotes, especially when it contains spaces.
How the bucket and region are chosen
- Without
bucket, the shortcode uses the Default bucket under Shortcode offloading in the settings. - Without
region, it uses the region of the Default bucket, or the Default region setting when no default bucket is set. It doesn’t look up the region of a different bucket you name, so for a bucket in another region, always addregion. - With Cloudflare R2, regions don’t apply, so
bucketandobjectare all you need.
Every shortcode download link is signed with your access keys, so they need read access to each bucket you link (for Amazon S3, s3:GetObject on that bucket; see Set up Amazon S3 for your store).
Special characters in object names
- Spaces work inside double quotes:
object="My File.pdf". - A
+or%20in the shortcode is read as a space, soobject=My+File.pdfalso points toMy File.pdf. - For a real plus sign in the name, write
%2B:object="size%2Bcolor.pdf"points tosize+color.pdf.
Use the shortcode outside product downloads
The shortcode also works in page or post content, where it outputs a signed link, for example <a href="[amazon_s3 object=brochure.pdf]">Download the brochure</a> (leave out the quotes inside the link’s href). That link isn’t protected by a purchase: anyone who can see the page gets a working link until it expires. Use it only for files you’d share freely, and keep paid files in product downloads.
Common issues
The download shows "No file defined"
WooCommerce got an empty file address, which means the shortcode is missing its object or bucket. Check that object is set and either bucket is set or a Default bucket is chosen in the settings.
The download shows an XML page with NoSuchKey
The object name doesn’t match a file in the bucket. Object names are case sensitive and include any folders. Copy the name from your provider’s console.
The download shows an XML page about the region or the authorization
The link was signed for the wrong region. Add the bucket’s region to the shortcode.
The download shows AccessDenied
Your access keys can’t read that bucket, or the link expired. Check the permissions for that bucket, then try a fresh download.