Keystone Documentation

Appearance

File Upload ​

Allow customers to upload files such as images, documents, or designs for product customization — as a single file or multiple files with per-option limits and type restrictions.

Overview ​

File Upload is an input option type that enables customers to upload files from their device. It's ideal for collecting artwork, logos, designs, documents, or any files needed for custom products or orders.

Use File Upload for:

  • Custom artwork or designs
  • Logos for printing or engraving
  • Product images or references
  • Documents or specifications
  • Photos for personalization

Key characteristics:

  • Single file (default) or multiple files per option, with a minimum/maximum count
  • Restrict accepted file types by group (Images, Documents, etc.) or individual extension
  • Can be marked as required
  • Validates file type, count, and size before checkout
  • Fully stylable — trigger, drop zone, file list, and feedback colors (see File Upload Styling)

Configuration ​

Basic Settings ​

SettingDescription
LabelOption name displayed to customers (e.g., "Upload Your Logo")
Option is required for this option setIf enabled, customers must upload a file before adding to cart
Hide Label from storefrontIf enabled, only the file upload button is shown (label is hidden)

Advanced Settings ​

SettingDescription
Internal LabelAdmin-only identifier (replaces label in options list)
Help TextAdditional guidance shown to customers (based on display mode)
Allow multiple filesOff by default. Turns this option into a multi-file uploader — see Multiple Files
Minimum files / Maximum filesOnly shown once Allow multiple files is on — see Multiple Files
Allowed file typesRestrict which file types customers can upload — see Allowed File Types

How to Add File Upload ​

  1. Navigate to Option Sets and open your option set
  2. Click Add Option
  3. Select File Upload from the Option Type modal
  4. Enter a Label (e.g., "Upload Your Design")
  5. Check Option is required if file upload is mandatory
  6. (Optional) Click Advanced Settings to add Internal Label, Help Text, enable multiple files, or restrict file types
  7. Click Save in the contextual save bar

Multiple Files ​

By default, a File Upload option accepts a single file — this behavior is unchanged from before and uses the same wire format, including edit-in-cart.

Turning on Allow multiple files switches the option to accept several files at once:

SettingDefaultWhat it does
Allow multiple filesOffEnables multi-file mode for this option. Min/max fields only appear once this is on
Minimum filesEmpty (no minimum)Customers must upload at least this many files before the option validates
Maximum filesEmpty (no maximum)Customers can't upload more than this many files. Hard-capped at 10 regardless of what's entered

Why 10?

The cart line only reserves 10 file-property slots per option, so Maximum files can't be set above that ceiling.

On the Storefront ​

  • Customers click the upload trigger (a button, a drop zone, or both — see File Upload Styling) to add files, one at a time or several at once depending on their device's file picker
  • Each added file appears as its own row in the file list, with a Remove control to take it back out
  • Trying to add-to-cart with fewer than the minimum, more than the maximum, or a disallowed file type blocks the submission and shows the relevant error message

Cart Properties ​

Each uploaded file becomes its own line-item property, named after the option's label with a number appended once there's more than one file:

  • Single file (or multi-file option with only one file uploaded): the property is named exactly like the option label — e.g. Logo
  • Multiple files: each file gets its own numbered property — e.g. Logo 1, Logo 2, Logo 3

This keeps existing single-file cart lines byte-identical to before — nothing changes for options that don't use multiple files.

Allowed File Types ​

Restrict which file types a File Upload option accepts using one of three modes:

ModeWhat it does
Allow all (default)No restriction — customers can upload any file type
Allow only selectedCustomers can only upload the file types you check
Block selectedCustomers can upload anything except the file types you check

When a mode other than Allow all is selected, pick from seven file type groups. Each group expands to let you check individual extensions instead of the whole group:

GroupExtensions
Images.png, .jpg, .jpeg, .gif, .webp, .svg
Documents.txt, .doc, .docx, .rtf, .pdf
Spreadsheets.csv, .xls, .xlsx
Presentations.ppt, .pptx
Audio.mp3, .wav, .ogg, .m4a
Video.mp4, .mov, .avi, .webm
Archives.zip, .rar, .7z

Checking a group selects every extension in it; unchecking individual extensions within an expanded group leaves the rest checked.

File Requirements ​

File Size ​

Every uploaded file is capped at 20 MB, regardless of type — this limit is fixed and isn't configurable per option or per store.

File Storage ​

  • Uploaded files are securely stored
  • Files are attached to the order
  • Accessible from order details in Shopify admin
  • Files remain available for order fulfillment

Error Messages ​

Five validation messages can be customized under Storefront Settings → Validation and Inventory. Leave any of them blank to use the default shown below.

MessageDefault textPlaceholders
File type not allowed message{option} does not accept this file type{option}, {types}
Minimum files message{option}: please upload at least {min} file(s){option}, {min}
Maximum files message{option}: you can upload up to {max} file(s){option}, {max}
File too large message{option}: file exceeds the {size} size limit{option}, {size}
Combined files too large message{option}: combined files exceed the {size} size limit{option}, {size}

Immediate feedback while picking

The Maximum files message also appears instantly the moment a customer tries to add more files than allowed — before they even attempt to add the option to cart.

Customer Experience ​

Upload interface:

  1. Customer clicks the upload trigger (button and/or drop zone, per your styling)
  2. Device file picker (or drag-and-drop) opens
  3. Customer selects one or more files, depending on the option's mode
  4. Each file appears as a row in the file list with its name, size, and a Remove control
  5. Customer can remove any file and add more, up to the configured maximum

Before adding to cart:

  • Required uploads must be completed
  • File count must satisfy Minimum/Maximum files (multi-file options)
  • Disallowed file types are rejected
  • Oversized files (over 20 MB, or combined over the limit) are rejected
  • Error messages guide corrections

Buy It Now hides when a file is selected

This is expected behavior, not a bug — files can only be attached through the regular add-to-cart flow, the same as it has always worked for single-file uploads.

Use Cases ​

Custom Logo Upload ​

Label: Upload Your Logo Required: Yes Help Text: Accepted formats: JPG, PNG, SVG. Minimum 300 DPI for best quality.

Result: Required file upload for customers to provide their logo for printing

Multiple Product Photos ​

Label: Upload Reference Photos Required: No Allow multiple files: Yes, Minimum 1, Maximum 5 Allowed file types: Allow only selected — Images

Result: Customers can upload 1–5 reference photos, each landing on the order as its own numbered property (e.g. Upload Reference Photos 1, Upload Reference Photos 2)

Design Artwork ​

Label: Upload Design Artwork Required: Yes Help Text: High-resolution images (min 1200x1200px) work best. We accept JPG, PNG, PDF. Allowed file types: Allow only selected — Images, Documents (PDF)

Result: Required upload for custom design artwork restricted to image and document formats

Reference Photo ​

Label: Upload Reference Photo Required: No Help Text: Optional: Upload a photo of what you'd like us to create

Result: Optional file upload for customers to provide reference images

Document Upload ​

Label: Upload Specifications Required: No Internal Label: Customer Spec Document Help Text: Upload PDF or Word document with your requirements Allowed file types: Allow only selected — Documents

Result: Optional document upload restricted to document formats

Styling ​

File Upload has its own dedicated styling — the upload trigger (button/drop zone), file list, and feedback colors are all configurable via named templates, the same way Accordion, Swatches, and Tabs work.

See File Upload Styling for the full settings reference, and Sandbox & Live Preview for how to preview upload states (complete, rejected, drag-over) while you style.

Best Practices ​

Provide clear guidance:

  • Use Help Text to specify file requirements
  • List accepted file types
  • Mention size or resolution requirements
  • Explain what the file will be used for

Set appropriate requirements:

  • Mark as required only when file is essential
  • Consider making optional for reference uploads
  • Test the upload flow from customer perspective
  • Ensure error messages are helpful

Communicate file specifications:

  • Specify minimum resolution for print quality
  • Mention the 20 MB per-file size limit if it matters for your use case
  • List preferred file formats
  • Provide examples of good uploads

Consider upload context:

  • Place upload option near related settings
  • Use Descriptive Text to provide instructions
  • Link to file preparation guides if needed
  • Offer support for file-related questions

Handle file quality:

  • Request high-resolution files for printing
  • Explain DPI requirements (e.g., 300 DPI)
  • Mention color mode if relevant (RGB vs CMYK)
  • Provide file preparation tips

Test on mobile devices:

  • File uploads work on mobile browsers
  • Camera roll access on smartphones
  • Test upload flow on various devices
  • Ensure button is easily tappable

Troubleshooting ​

Upload button not appearing: Check that File Upload option type is selected and saved

File rejected: Verify file type is supported and within the 20 MB size limit

Too few/too many files: Check the option's Minimum files / Maximum files settings

Upload fails: Check internet connection, try a smaller file, or a different format

File not attached to order: Ensure upload completed before adding to cart

Buy It Now missing: Expected — see the note above