WooCommerce Uploads documentation

Installation

  1. Make sure WooCommerce is installed.
  2. Download the .zip file.
  3. Upload the entire ‘woocommerce-uploads’ directory into the ‘/wp-content/plugins/’ directory.
  4. Activate the plugin through the ‘Plugins’ menu in WordPress.
  5. Configure the plugin by going to WooCommerce -> Uploads (see ‘Getting started’ on this page for more information).
  6. Enter the license key for this plugin in our WP Fortune plugin to get support and updates.

Getting started

mini_screen1
Before you start using WooCommerce Uploads, it is important a few settings are set up correctly. You can find the WooCommerce settings page  by clicking on (or hovering over) ‘WooCommerce’ in the WordPress admin panel and click on ‘Uploads’. You will now see the settings page where you can configure the plugin to your needs.

Check your upload path

By default the upload path is specified by the plugin, this can be changed if you want to store your uploads in another directory. It’s important you check (and change if needed) the upload path before you let customers upload files. This setting can be found under ‘General settings’. Although the plugin would still work properly, it is not recommended to change the upload path once customers have uploaded files. The change is not backwards compatible, i.e. already uploaded files are not moved to the new directory.

Enable upload for current products

If you already have products in your webshop and you want to let customers upload files for those products, you can use the ‘Enable upload for all current products’ button (under ‘General settings’). WooCommerce Uploads will perform a check on all products and, if no upload settings were found for a product, automatically enables upload and attach the default upload set to it. mini_screen2 Please check your default upload set carefully, since this action cannot be undone. If you made a mistake in your default upload set, a typo in your title for example, you will have to manually change the title later in the upload set for each product. See ‘Create a default upload set’ for more information.

Create a default upload set

mini_screen3

A default upload set is a set of upload boxes which will be used in two cases:

  • When you click on ‘Enable upload for all current products’ – All current products in your webshop will have the default upload set now.
  • When you add a new product to your webshop and the ‘Default upload’ setting is enabled. The newly added product will have the default upload set. (You can fully customize this upload set on product level anytime).

For more information about creating an upload set, see ‘Create an upload set‘ in the ‘Upload sets’ section.

Settings

Uploader

  • Uploader type – AJAX supports larger files because it will split up the files (this is the recommended setting). Choose HTML if you have any trouble using the AJAX uploader. If you choose the HTML uploader, please keep in mind that all uploads combined cannot exceed your PHP max_upload_size setting (usually 8MB).
  • Show dropzone – AJAX only. Shows a zone where customers can drag and drop their files into.
  • Max. chunk size – AJAX only. Large files will be splitted up into multiple, smaller parts (chunks). When the upload is finished, the parts will be combined together again to create one file. Don’t set this value higher than your PHP max_upload_size setting (usually 8MB).

General settings

  • Default upload – When you add a new product to your webshop, this product will have uploads enabled by default. The default upload set will be used here.
  • Enable upload all products – Click this button if you want to enable uploads for all current products in your webshop. See ‘Enable upload for current products’ in the ‘Getting started‘ section for more information.
  • Styling – We’ve created some default stylings for the upload boxes which will be visible for the customer. Check this option if you would like to make use of this. Disable this option if you want to use your own styling.
  • Order tracking page – Select the order tracking page. We need this information to create a correct url in the email the customer receives after their order is placed.
  • Position – You can choose where you want to show the upload boxes. This can be before the order details or after the order details on the order detail page.
  • Thank you page – Directly after checkout, the customer will be redirected to a ‘thank you’ page. If you want to show the upload boxes on this page, check this option.
  • Upload path – The absolute path to the directory where all the uploads will be stored. For each order id / number, a subdirectory will be created in this directory. In this subdirectory, the uploads will be stored.
  • Upload procedure – If a customer orders multiple items of a single product you can choose whether you want to let them upload files for each item or upload files for all items at once. For example: If someone orders 5 t-shirts (the same product), you can let the customer upload a picture 5 times (each item get it’s own picture) or let the customer upload 1 picture (all 5 items get the same picture).
  • Order numbering – By default the order ID will be used to create a subdirectory where the uploads will be stored. If you are running a plugin which will let you choose your own order numbers for WooCommerce, you can set this option to ‘Order number’. This custom order number will then be used as the subdirectory.
  • Customer delete – If you want to give the customers the ability to delete their uploaded files. Files can only be deleted when a file is declined or is awaiting approval of the shop manager. Once a file is approved customers can’t delete files anymore.
  • Required status(es) – The status(es) an order needs to be to let a customer upload files. If an order doesn’t have the status you defined here, no upload boxes will be shown.
  • Dynamic variation support – If you’re using a plugin which let’s customers customize your product (such as WooCommerce (Gravity Forms) Product Add-ons, Woo Table Based Pricing etc.), please enable this option. Default this setting is enabled. Only keep this setting disabled if you’ve had a version below 1.1.3 installed.

Preview thumbnail settings

  • Preview thumbnails – If you want to generate thumbnails for uploaded files which will be shown to the customer. If you have the GD library installed on your server, jpg, gif and png files are supported. If you have Imagick installed the plugin can also create thumbnails of psd, pdf, ai and eps files.
  • Preview thumbnail size – The width and height of the generated thumbnails. Sizes must be given in pixels.
  • Crop thumbnails – If you want to let thumbnails crop to the sizes, given in the ‘Preview thumbnail size’ setting. If disabled, thumbnails may look stretched.
  • Thumbnail quality – The quality of the generated thumbnails. The higher the quality, the bigger the filesize of the thumbnails will be.

Default upload set

For more information about creating an upload set, see the ‘Create an upload set‘ section.

Custom messages

mini_screen4

  • Custom messages – If you want to write your own messages which will be shown to the customer after a file has been uploaded, check this option.
  • Not checked – This is the message a customer will see directly after a file is uploaded. Default: ‘Your file will be manually verified.’
  • Declined files – The message the customer will see when the shop manager declines a file. Default: ‘We have found a problem with this file. Please upload a new file.’
  • Accepted files – The message the customer will see when the shop manager accepts a file. Default: ‘Your file is approved.’
  • Upload description – A short description that will be shown to the customer. This is a general description that will be shown above all the upload boxes.

Customer notifications

When customers have finished their order, they will receive an e-mail containing the order confirmation. If this order contains one or more products with uploads enabled, an extra link can be added to this e-mail. The settings below are applied to this.

  • Link to customer e-mail – Choose to which page you want to link to in the e-mail. This can be the order detail page (which requires an account), the order tracking page (which doesn’t require an account) or no link, if you want to disable this.
  • E-mail text customer e-mail – The text which will be used as the link text, will be sent to the customer in the e-mail. You can set a singular sentence (when only a single file can be uploaded) or a plural sentence (when multiple files can be uploaded).

Admin notifications

  • Admin notifications – If you want to receive notifications when a customer changes, deletes or uploads a file. You won’t receive an e-mail anytime a customer makes a change in his/her order, but you will get an overview with changed orders once in a while (see the Recurrence setting).
  • Recurrence – How many times you want to receive an e-mail.
  • Recipients – The recipients of this e-mail. You can add multiple e-mails in here, seperated by a comma.

Upload sets

An upload set is simply a collection of ‘upload boxes’. Each product has one upload set which can contain, in theory, an unlimited amount of upload boxes. Each upload box represents one kind of upload and has it’s own settings.

Example:
You sell t-shirts on your website and you want to let customers upload their own images for the front- and backside of a t-shirt. For the frontside you need a small logo on the upper left side, and a bigger picture on the middle of this t-shirt. For the backside you need just one picture.

You can now create 2 upload boxes for this product:

  • Frontside – With a maximum number of uploads of 2.
  • Backside – With a maximum number of uploads of 1.

Create an upload set:

There are two kind of upload sets; a ‘default upload set’ (see ‘Create a default set’ in the ‘Getting started‘ section for a more detailed explanation) and an upload set on product level. You can create a default upload set on the plugin setting page and an upload set on product level on the product edit page of WooCommerce in the WordPress admin panel (the plugin adds an ‘Uploads’ section here). The way you create / customize an upload set is exactly the same for both ways.

mini_screen5

Example of one upload set, containing two upload boxes

Add a new upload box

Click on the green ‘Add new upload box’ button to add a new upload box to your upload set. A new box will appear which you can customize to your needs.

Delete an upload box

Click on the red ‘Delete’ button if you want to remove an upload box.

Rearrange upload boxes

Click somewhere in the grey area of an upload box when the ‘move’ cursor appears. You can now drag the upload box to a new position. The positions of the upload boxes you see here, will also be visible to the customer in this order.

Warning: It is strongly recommended not to change the positions of the boxes once you have saved it (you can still add, delete or change settings without any harm). If a customer uploads a file, it will be attached to the position of the box, so the plugin knows which upload belongs to which upload box. This warning only applies for editing upload boxes on product level.

Upload box settings

You can change the upload settings for each upload box by clicking on the ‘More settings’ button.

  • Upload title – A very brief description of the upload box (one word is enough)
  • Upload description – A short description of what the uploads are for
  • Number of uploads – The maximum amount of uploads for this upload box
  • (Dis)Allowed file types – The allowed or disallowed file types. You can fill in file extensions, seperated by a comma. Due to security reasons, it’s not recommended to use ‘disallow’ here.
  • Max. upload size – The maximum upload size for each upload (see ‘Number of uploads’).
  • Min. resolution – If the uploaded file is an image, you can specify the minium width and/or height the image needs to be.
  • Max. resolution – If the uploaded file is an image, you can specify the maximum width and/or height the image needs to be.
  • Show for variations – This setting is ONLY visible on the product page and when the product is a variable product. Here you can choose if you only want to show the upload box for specific variations of the product.

Frequently asked questions (FAQ)

Is WooCommerce Uploads compatible with the old WooCommerce Upload My File plugin?

Yes, if you have the WooCommerce Upload My File plugin installed, WooCommerce Uploads will check for old settings and try to restore them. If customers already uploaded files with the Upload My File plugin, it will also try to restore them, so they appear correctly on the WooCommerce order detail page in the WordPress admin panel.

I already have products in my webshop, can I activate uploads for those products?

Yes, see our documentation how to enable uploads for current products in your webshop.

Where can I change the plugin settings?

You can change the plugin settings by clicking (or hovering over) the WooCommerce button in the WordPress admin panel and selecting ‘Uploads’ from the submenu.

What is an upload set?

An upload set is simply a collection of ‘upload boxes’. Each product has one upload set which, in theory, can contain an unlimited amount of upload boxes.

What is an upload box?

An upload box represents one kind of upload and has it’s own settings. See our documentation for more information about how to configure your own upload boxes.

How many upload boxes can I add?

As many as you want, there is no limit.

Where can I enable / customize uploads per product?

If you want to customize your uploads per product, you can simply go to the products overview page in the WordPress admin panel, click the product for which you want to customize uploads and search for the ‘Uploads’ section. Here you can enable uploads and / or customize your upload boxes.

What if my customer orders multiple items of the same product?

On the WooCommerce Uploads settings page in the WordPress admin panel, you can choose the upload procedure for uploads when a customer orders multiple items of the same product. See our documentation how you can do this.

Can I change the directory where my uploads are stored?

Yes, you change the upload path under ‘General settings’ on the plugin settings page.

Why is my file not uploading?

This can be a lot of things. The file may be uploaded, but don’t show up. Or the file is not uploaded at all. So please go through the checklist below if you (or your customer) have any problems with uploading files:

  • Do you see any errors?
  • Is your upload path set up correctly?
  • Is your upload path writable by the server? (755 are the recommended permissions, on some servers 777 is needed)
  • Is your file actually uploaded in the directory you’ve filled in in the ‘upload path’ setting? (you can check this with a FTP program)
  • If you use the AJAX uploader, does the ‘Max. chunk size’ exceeds the PHP max_upload_size limit? (usually 8MB)
  • If you use the AJAX uploader, does changing the uploader type to ‘HTML’ solves the problem?
  • If you use the HTML uploader, does the ‘Max. upload size’ of all upload boxes combined exceeds the PHP max_upload_size limit? (usually 8MB)
  • If you refresh the page where you have uploaded the file, is the file still not visible?
  • What happens when you use another browser?

If you use the AJAX uploader, the progress bar should turn green when a file is successfully uploaded or red when an error occurs. If, for some reason, the progress bar does not work or you have any other strange problems with the AJAX uploader, please try to clear your browser cache completely (you can check your browsers website how to do this).

Where can I accept / decline files a customer uploaded?

You can accept / decline files by going to the relevant order in the WordPress admin panel. On your right you will find a section ‘Uploaded files’. Here you can bulk accept / decline files for this order.

Where will the upload boxes appear?

You can find the upload boxes on the ‘Thank you page’ and/or the order detail page. The ‘Thank you page’ is the page you will see directly after checkout. You can find the order detail page by clicking on ‘My account’. You will see an ‘Upload’ button here. By clicking on ‘Upload’, you will be redirected to the order detail page.

Why don’t I see the upload fields on the order detail page?

If the upload doesn’t show up on the order detail page, please check the ‘Required status(es)’ on the plugin settings page under ‘General settings’. Also check if uploads are enabled for the ordered products.

Why don’t I see the upload fields on the thank you page?

To enable uploads on the thank you page, you have to check the ‘Show on thank you page’ option on the plugin settings page under ‘General settings’. If the upload boxes still don’t show up, please check the ‘Required status(es)’ on the settings page under ‘General settings’. Also check if uploads are enabled for the ordered products.

What type of files are supported for the uploads?

Any files you want. You can allow or disallow certain filetypes per upload box.

How can I change the order of the upload boxes?

You can click in the grey area of an upload box and drag the box up or down to change the order of an upload box. It is strongly recommended not to change the positions of the boxes anymore once you have saved it (this does not apply on the default upload set).

Can I add my own description for the uploads?

Yes, for each upload box you can add your own description. See our documentation for more information about how to configure your own upload boxes.

Can my customer delete an uploaded file?

Yes, customers can delete their own files until they are reviewed by the shop manager or when a file is rejected. If you don’t want to use this option, you can turn it off on the plugin settings page under ‘General settings’. If you turn this option off, customers can only upload files, but can never delete it.

Can I also let my customer upload files before checkout?

Yes, you can with our WooCommerce Uploads Before Add-On.

Can I receive an e-mail when a customer uploads / deletes a file?

Yes, you can enable admin notifications. You can do this by clicking on ‘Messages & Notifications’ tab on the plugin settings page. Under ‘Admin notifications’ you can enable the admin notifications. When you enable this setting, you will receive an e-mail every day, every hour or twice a day (you can set this yourself) with an overview of orders where uploads have been changed.

Can I let customers upload multiple files for a single product?

Yes, you can create an unlimited amount of upload boxes for each product. See our documentation for more information about how to configure your own upload boxes.

What type of files are supported for thumbnail creation?

This depends on your server settings. If the GD library is installed on your server (which is usually the case) you can create thumbnails of jpg, gif and png files. If you also have Imagick installed, psd, pdf, ai and eps files are supported as well. The plugin will automatically check your server settings and always try to use Imagick. If Imagick is not found, it will switch to GD.

How do I change the size of the generated thumbnails?

You can set your own thumbnail sizes on the plugin settings page under ‘Preview thumbnail settings’. If ‘Preview thumbnails’ is enabled, you will see the option to configure the height and width of the thumbnails to your needs.

Can I translate WooCommerce Uploads?

Yes, WooCommerce Uploads is fully supported by the WordPress translation service so you can always have the plugin in your own language if there are language files available for this plugin. Of course you can always write your own translation files.

Can I change my uploadbox settings for all products at once?

Yes, we have created a free add-on which allows you to change some settings (like the maximum uploads amount, allowed filetypes etc.) for all of your upload boxes for all products for which uploads are enabled. You can download this add-on here. After activating this plugin, you will see an extra tab on the WooCommerce Uploads settings page.

I can’t change my upload path, why is this?

For security reasons, you can’t enter an upload path which is outside your root directory (the directory where your WordPress install is located). If you really want to disable this check, you can add the following code to your theme’s functions.php:

function wpf_uploads_path_check_disable() {
return true;
}

Can I preserve the filename of the uploaded file?

By default files are stored with a different name than the original filename, so the plugin still knows to which order, which product and which upload box a file belongs to in case something goes wrong. If you want to have the original filename in the uploaded file, you can add the following code to your theme’s functions.php:

function wpf_uploads_preserve_filename() {
return true;
}

This way, the original filename will be appended to the ‘new’ filename.

Can I show upload boxes only for specific product variations?

Yes, when the product is a variable product, an extra option ‘Show for variations’ will appear for each upload box. Here you can choose if you want to show the upload box for all variations or only for one or more specific variations.

How can I enable file uploads for any file type?

If you really want to let your customer upload files of any file type, you can simply fill in ‘*’ (without the quotes) in the ‘(Dis)allowed filetypes’ setting for a single upload box. You can set the dropdown either to ‘Allow’ or ‘Disallow’.

Warning: it is not recommended to use this, since people can upload malicious files to your server.

Can my customer download an uploaded file?

Yes, if you want to let your customers download their own uploaded files, you can enable this on the plugin settings page. Your customer then can dowload their files by clicking on the file name once a file is uploaded.

What does the ‘Dynamic variation support’ setting mean?

Since version 1.1.3 we have added support for plugins that allow customers to customize products by adding their own options to it. We named this ‘Dynamic variations’ in our WooCommerce Uploads plugin. We strongly recommend to keep this setting enabled at all times (even if you don’t use dynamic variations). If you have ever had a version of the plugin below 1.1.3 installed , we recommend to keep this setting disabled. Because with this setting enabled, uploads are stored differently, but we have created this setting to make it compatible for users who had a previous version installed.

Some plugins this works for:

  • WooCommerce Product Add-ons
  • WooCommerce Gravity Forms Product Add-ons
  • WooCommerce Measurement Price Calculator
  • Woo Table Based Pricing
  • etc.

I only see one upload box, even if I have multiple items of the same product in my order / cart, how can I fix this?

Make sure you have the latest version of WooCommerce Uploads and make sure you have the ‘Dynamic variation support’ setting enabled.

I’m getting a 200 HTTP error when uploading a file, how can I fix this?

The 200 http error is a general error, which appears when an unknown error occurs during uploading. Usually this error is caused by the thumbnail creation of larger files. Because our plugin uses the same functionality for creating thumbnails as the default WordPress media uploader does, you can easily test this by uploading an image, which fails in our plugin, through the default media library from WordPress. If this also throws a HTTP error, the problem is probably server-related. If you get this error, try to disable thumbnail creation on the WooCommerce Uploads settings page.

Developer notes

Styling

By default WooCommerce Uploads adds some default styling so it makes the plugin completely ready-to-use. We used simple grey-scaled colors, so it fits easily into almost any theme. Of course you can create your own styling if you want. To do this, we recommend to disable the ‘Styling’ setting on the ‘General settings’ page of the plugin and then use our stylesheet as a base for your own. You can find our stylesheet in ‘/assets/css/style.css’ in the plugin directory.

If a customer uploads a file, the uploaded file will be visible to the customer. Each uploaded file has a <div> which contains a class with the extension of the uploaded file and the status of it so you can add your own styling depending on the extension and/or status of the uploaded file. For example:

<div class="wpf-umf-single-uploaded-file jpg declined">
The status classes can be: approved, declined or on-hold.

Hook into process after upload

Developers can make use of our hook to hook into the process after a single file has been uploaded. This hook is only called when a file is succesfully uploaded.

We will explain how you can use this hook and which parameters you can use.

You can place the following code in your functions.php (or a plugin, or anywhere else you want to place this):

add_action('wpf_upload_complete', 'wpf_upload_complete_callback', 10, 4);      

function wpf_upload_complete_callback($order_id, $product_id, $file_path, $mode) {

   // Your code here

}

 

$order_id = The order id, this is empty if the upload is done before checkout.
$product_id = The id of the product (or variation) where the upload is attached to.
$file_path = The absolute file path to the file.
$mode = Either ‘before’ or ‘after’, depending whether the upload is done before or after checkout.

Add custom HTML after upload boxes

If you want to add custom HTML after the upload boxes, you can use our ‘wpf_umf_after_upload_boxes’ hook. You can use this hook to display a ‘Go to cart’ button directly after the upload boxes, a short description or any other HTML you want. The example below shows a ‘Go to cart’ button, only when the uploads are before checkout (the WooCommerce Uploads Before Add-On is needed for this).

add_action('wpf_umf_after_upload_boxes', 'wpf_umf_after_upload_boxes', 10, 1);

function wpf_umf_after_upload_boxes($upload_mode) {

     if ($upload_mode == 'before') {

          echo '<a class="button" href="/hc/admin/articles/'.WC()->cart->get_cart_url().'">'.__('Go to cart').'</a>'; }

     else {

          // Here something if uploads are after checkout

     }

}

How to solve problems with W3 Total Cache plugin

If you’re using the W3 Total Cache plugin, you could experience some problems with the AJAX uploader in WooCommerce Uploads when you enable JS minifying in the W3 Total Cache plugin. If JS minifying is enabled, the ‘Select files’ and ‘Start upload’ might not work correctly.

To solve this, follow the next steps:

Step 1:

Go to ‘Performance’ in the WordPress admin menu. Now click on ‘Minify’ in the submenu.

Step 2:

Find the ‘Never minify the following JS files’ setting.

Step 3:

screenshot total cache

 

Add the next two lines to it:

wp-includes/js/jquery/jquery.js
wp-includes/js/plupload/plupload.full.min.js

Step 4:

Click ‘Save all settings’ to save the settings. You’re done!

Now go the upload page and hit CTRL + F5 (on Windows) to do a ‘hard’ refresh or clear your browsers cache. Now try to upload again.

Changing the filename of uploaded files

By default files are stored with a different name than the original filename, so the plugin still knows to which order, which product and which upload box a file belongs to in case something goes wrong. If you want to make changes to the filename, you can use our built-in filter:

The example below shows how this filter is used to change the filename to the sku of a product.

$filename = The default filename (including extension)
$original = The original filename (including extension), this is the filename the customer who uploaded the file has named the file
$extension = The extension of the file, for example: ‘jpg’
$product_id = The product this upload is attached to. In case of a variable product, this is the variation ID.
$order_id = The order ID, the files are uploaded to.

Add the following code to your theme functions.php or in a custom plugin.

add_filter('wpf_umf_filename', function($filename, $original, $extension, $product_id, $order_id) {

    $product = new WC_Product($product_id);

    return $product->get_sku().'.'.$extension;

}, 10, 5);

Warning: If a customer can upload multiple files, be careful each file is unique. Otherwise files can be overwritten!

We do not give support for custom code, however if you need us to write us the code please ask us for a quote.

Make your uploads more secure

Uploads are stored in folders under wp-content/uploads and are saved with a different name. This makes it hard to find them, however, some hosts enable directory listing which allows people to browse your file and folder structure. To disabledirectory listing you can easily add the following to your main .htaccess file:

Options -Indexes

Add column with number of uploaded files

In order overview you can add an extra column with information about the number of uploaded files.

This can be done with a small piece of code which you can add to your theme functions.php or in a custom plugin.

The following code is just an example, so test it first on a development environment.

 

/* * ******************************************************** *
* Add column called "Files" to order overview page
************************************************************ */
add_filter('manage_edit-shop_order_columns', 'show_product_order', 15);

function show_product_order($columns) {
$new_columns = (is_array($columns)) ? $columns : array();
$new_columns['files'] = __('Files'); return $new_columns;
}

 

/* * ******************************************************** *
* Count number of uploaded files and add it to "Files" column
************************************************************ */
add_action('manage_shop_order_posts_custom_column','wpf_custom_shop_order_column',10, 2);

function wpf_custom_shop_order_column($column) {
global $the_order;

// If is "Files" column...
switch ($column) {
case 'files' :

// All upload data is stored inside order meta data
$uploaded_files=get_post_meta($the_order->id,'_wpf_umf_uploads');

// Set starting of files to 0
$files=0;

// We loop through all arrays to count the number of files
foreach ($uploaded_files as $products) {
foreach ($products as $product) {
foreach ($product as $upload_boxes) {
foreach($upload_boxes as $box) {
foreach ($box as $file) {

// Count the number of files
$files++;

}
}
}
}
}

// Outputs the number of files to the column
printf( esc_html( _n( '%d File.', '%d Files', $files, 'woocommerce' ) ), $files );

break;
}
}