--- title: "Get started with Amazon S3 Storage" url: "https://kestrelwp.com/docs/get-started-with-amazon-s3-storage/" description: "Serve your WooCommerce downloadable products from an Amazon S3 or Cloudflare R2 bucket." published: "2026-10-06T20:23:27+00:00" modified: "2026-10-06T20:23:27+00:00" --- Amazon S3 Storage serves your WooCommerce downloadable products from an Amazon S3 or Cloudflare R2 bucket instead of your web server. It uploads each product’s downloadable files to your bucket in the background, then sends customers who click a download link to a short-lived signed link for that file. ![Amazon S3 Storage: overview (the Downloadable files table with the S3 status column)](https://kestrelwp.com/wp-content/uploads/2026/10/amazon-s3-s3-01-docs-01.png)The plugin handles product downloadable files only. It doesn’t move your media library, product images or other uploads to the bucket, and it keeps the local copy of every file on your server as a fallback. ## When you’d use this - You sell large files, such as video courses, audio albums or software, and want to take the download traffic off your web server. - Your host limits bandwidth or file sizes. - You already keep your files in a bucket and want to link product downloads to them. - You want download links that stop working after a set number of minutes. ## Requirements - WordPress 6.3 or later, WooCommerce 8.2 or later, and PHP 7.4 or later. - Compatible with WooCommerce’s cart and checkout blocks and High-Performance Order Storage. - An Amazon Web Services account with an S3 bucket, or a Cloudflare account with an R2 bucket. Backblaze B2, Wasabi and DigitalOcean Spaces work experimentally with a code snippet. - The PHP OpenSSL extension, if you save your access keys in the settings. Without it, store the keys as constants in your `wp-config.php` file instead. - Store administrators and shop managers can change the settings. ## Install and activate How you get updates depends on where you bought Amazon S3 Storage: - **Bought on kestrelwp.com:** download the plugin from the **Licensed downloads** tab of your kestrelwp.com account and install it. Then go to **Settings » Amazon S3 Storage for WooCommerce activation** and activate the key from your **License keys** tab to receive updates. See [using sites against your activation limit](/docs/using-sites-against-your-activation-limit/) for how activations count. - **Bought on WooCommerce.com:** install the plugin from your WooCommerce.com account. Updates come through your WooCommerce.com connection, with no license key to enter. For upload, FTP and update steps, follow [how to install and update WooCommerce extensions](/docs/install-update-woocommerce-extensions/). ## Set up Amazon S3 Storage ### 1. Prepare your bucket and access keys Create a bucket and a set of access keys that can reach it. Follow the guide for your provider, then come back here: - [Set up Amazon S3 for your store](/docs/create-an-amazon-s3-bucket/) (an IAM user, its permissions and a bucket) - [Connect Cloudflare R2](/docs/connect-cloudflare-r2/) (an R2 API token, a bucket and the endpoint) - [Connect other S3-compatible providers](/docs/s3-compatible-providers/) (Backblaze B2, Wasabi and DigitalOcean Spaces, experimental) ### 2. Connect your provider Go to **WooCommerce » S3 storage**, which opens the **S3 storage** tab under **WooCommerce » Settings**. In the **Connection** section: 1. Choose your **Cloud service provider**: **Amazon S3** or **Cloudflare R2**. 2. Leave **Credentials location** at **Save credentials to database (encrypted)**, or choose the constants option to keep the keys in `wp-config.php`. 3. Paste your **Access key ID** and **Secret access key**. 4. For Cloudflare R2, paste your account’s S3 API URL into **Endpoint**. 5. Click **Save changes**. When the keys work, the page shows "Connected to Amazon S3." (or Cloudflare R2), and the rest of the settings appear. If you see "A connection to Amazon S3 could not be initialized" instead, the message says why; [Connection messages](/docs/troubleshoot-amazon-s3-storage/#connection-messages) explains each version of it. ![Amazon S3 Storage: Connect your provider](https://kestrelwp.com/wp-content/uploads/2026/10/amazon-s3-s3-02-docs-01.png)### 3. Choose a bucket and turn on automatic offloading In the **Automatic offloading** section, tick **Enable** and choose your bucket under **S3 bucket**. With Amazon S3, you can pick **Create a new bucket…** instead, enter a name and a region, and the plugin creates it when you save. Click **Save changes**, even if the bucket you want already shows, so the choice is stored. The other settings, such as how long download links stay valid, have sensible defaults. Each one is described in [Amazon S3 Storage settings](/docs/amazon-s3-storage-settings/). ### 4. Add or update a downloadable product Edit a downloadable product (or a downloadable variation) and add its file under **Downloadable files** the usual way, with **Add File** and **Choose file**. Click **Update** or **Publish**. The **Downloadable files** table now has an **S3 status** column. The file shows **Queued** when you save, then **Offloaded** once the upload finishes in the background. Reload the product page to see the status change. ![Amazon S3 Storage: Add or update a downloadable product (the Downloadable files table including Add File and Add S3 file shortcode)](https://kestrelwp.com/wp-content/uploads/2026/10/amazon-s3-s3-03-docs-01.png)Products you created before turning on offloading aren’t uploaded until you update each one in the product editor. The same goes for products added by a CSV import or another plugin. ### 5. Test a download Place a test order for the product, or use an order that already includes it, and click the download link in the order confirmation or **My account » Downloads**. The file downloads from your bucket. If it opens in the browser instead, such as an audio file or a PDF, set **Download behavior** to **Force download** in [the settings](/docs/amazon-s3-storage-settings/). ## How automatic offloading works When you save a product in the product editor, the plugin queues each new downloadable file from your media library for upload, and WooCommerce’s scheduled actions (Action Scheduler) upload it to your bucket in the background. Your local copy stays on the server. Each file shows one of these statuses in the **S3 status** column, and in the **S3:** field of the file’s details in the media library: | Status | What it means | |---|---| | **Queued** | Waiting for the background upload. | | **Processing** | Uploading now. | | **Offloaded** | In your bucket. Downloads come from the bucket. With Amazon S3, the badge links to the file in the AWS console. | | **Failed** | The upload didn’t work. Downloads use the local file. | | **Not found** | The file was offloaded but is no longer in the bucket. Downloads use the local file. | | **Shortcode** | The file URL is an S3 shortcode, so it’s never uploaded. | | **Disabled** | Automatic offloading is off. | | **Disconnected** | The plugin can’t reach your provider right now. | | **Unhandled** or **Unknown** | The file isn’t in your media library (for example, an external URL), or it was added since the last save. | Each file goes up in a single upload, which Amazon S3 limits to 5 GB. For a larger file, upload it to the bucket yourself and link it with the [S3 shortcode](/docs/amazon-s3-storage-shortcode/). Files already in a bucket don’t need offloading at all: the shortcode links a product download to any file in any of your buckets. ## What customers see Nothing changes for customers. Download links in the order confirmation, the order emails and **My account » Downloads** still point to your store, and WooCommerce still checks download limits, expiry and access before anything else happens. When a customer clicks a link, the plugin swaps in a signed link to the file in your bucket, and their browser downloads it from there. ![Amazon S3 Storage: What customers see (storefront My account » Downloads)](https://kestrelwp.com/wp-content/uploads/2026/10/amazon-s3-s3-04-docs-01.png)A signed link stays valid for the **URL validity period** (15 minutes by default) and is reused until it expires, so a copied link stops working after that. If your provider can’t be reached, or the file isn’t in the bucket, customers get the local copy from your server instead. While your access keys are saved, the plugin turns off WooCommerce’s approved download directories for the whole store, and **WooCommerce » Settings » Products » Approved download directories** says so. ## Common issues ### The settings show only the Connection section The plugin isn’t connected yet. Check the notice at the top of the page; [Connection messages](/docs/troubleshoot-amazon-s3-storage/#connection-messages) explains each one. ### A file stays on Queued The upload runs as a scheduled action. Go to **WooCommerce » Status » Scheduled Actions**, search for `s3_storage_upload_file`, and check that pending actions run. If none ever run, WordPress cron may be turned off on your site; ask your host to set up a server cron job. ### A file shows Failed or Not found Turn on **Debug mode**, then see [Offloading](/docs/troubleshoot-amazon-s3-storage/#offloading) in the troubleshooting guide for the causes and how to upload the file again. ## Keep learning - [Set up Amazon S3 for your store](/docs/create-an-amazon-s3-bucket/) - [Connect Cloudflare R2](/docs/connect-cloudflare-r2/) - [Link files with the S3 shortcode](/docs/amazon-s3-storage-shortcode/) - [Amazon S3 Storage settings](/docs/amazon-s3-storage-settings/) - [Troubleshoot Amazon S3 Storage](/docs/troubleshoot-amazon-s3-storage/)