README

Magento 2 Order Attachments Extension: Upload Files to Order Items at Checkout (Hyva + Luma)

Let customers attach files to specific order items during checkout. Panth Order Attachments adds a drag-and-drop upload widget to the product page, carries the files through the cart and checkout, and gives admins a searchable grid to download every uploaded file linked to its order item.

Product page: kishansavaliya.com/magento-2-order-attachments.html

Quick Answer

What is Panth Order Attachments? It is a Magento 2 extension that lets customers upload files to specific order items on the product page. The files travel through the cart and checkout and are stored in the panth_order_attachment table, linked to the sales order item.

What does it add to my store?

• A drag-and-drop upload widget on the product page, with thumbnail previews and progress bars.
• Files carried through cart and checkout and saved to the order item on placement.
• An admin grid under Panth Extensions > Order Attachments > Manage Attachments, with filters, thumbnail previews, and one-click downloads.
• A per-product attribute (panth_allow_order_attachment) to turn uploads on or off per product.
• File validation on both client and server: allowed extensions, max file size, and max files per item, all configurable.

Which themes are supported? Both Hyva (Alpine.js) and Luma (vanilla JS). The right template is loaded automatically based on the active theme.

What does it need? Magento 2.4.4 to 2.4.8, PHP 8.1 to 8.4, and the free mage2kishan/module-core package (version 1.0.17 or later).

Need Custom Magento 2 Development?

Get a free quote for your project in 24 hours for custom modules, Hyva themes, performance work, M1 to M2 migrations, and Adobe Commerce Cloud.

Visit our website: kishansavaliya.com  |  Get a quote: kishansavaliya.com/get-quote

Table of Contents

• Who Is It For
• Key Features
• Compatibility
• Installation
• Configuration
• How It Works
• Admin Management
• FAQ
• Support
• About Panth Infotech
• Quick Links

Who Is It For

• Print-on-demand stores selling custom t-shirts, mugs, canvas prints, or business cards where customers must supply artwork at order time.
• Personalised gift stores where customers upload a photo or design to attach to a specific item.
• Opticians and pharmacies that need customers to upload a prescription PDF before the order is fulfilled.
• B2B merchants who need customers to attach purchase orders, technical specs, or drawings to specific line items.
• Engraving and embroidery stores where each item needs a reference image or text file from the customer.

Key Features

Product Page Upload Widget

• Drag-and-drop file upload with real-time progress bars on the product page.
• Thumbnail previews for images, file-type badges for documents.
• Multi-file support so customers can attach more than one file per item (max count is configurable).
• Optional customer note field travels with each attachment.
• Per-product control through the panth_allow_order_attachment attribute, so only products that need uploads show the widget.

Cart, Minicart, and Checkout

• Attachment cards visible in cart, minicart, and checkout order summary so customers can confirm what they uploaded.
• Cart edit support so customers can add, replace, or remove attachments when they update a cart item.
• Files are carried through to order placement via a sales_order_place_after observer.

My Account: Order View

• Attachment cards with download links appear on the frontend order view page under My Account.
• Image lightbox lets customers click to enlarge image attachments from the cart, checkout, and order view on both Hyva and Luma.

Admin Grid and Order Tab

• Dedicated admin grid under Panth Extensions > Order Attachments > Manage Attachments, showing thumbnail, filename, product link, order ID, customer, file size, extension, and status.
• Filters and search by order ID, customer email, SKU, date range, file type.
• One-click download from the grid.
• Order Attachments section on the admin order view page, listing files linked to that order.
• ACL resources for view and download permissions.

Security

• SHA-256 hashed filenames on disk so original user-supplied names never touch the file path.
• Extension allowlist enforced server-side, with a hard deny-list for executable types (php, phtml, sh, jsp, and others) enforced via Panth\Core\Security\UploadExtensionPolicy.
• MIME type validation so the file contents are checked, not just the extension.
• File size enforcement on both client (JS) and server (PHP).
• Honeypot field and rate limiting (20 uploads per 10-minute window) to block bot submissions.
• Ownership validation on download and thumbnail endpoints so customers can only access their own files.
• Soft-delete only so customers cannot hard-delete files; admins manage deletions through the grid.
• Files are stored in var/order_attachments/, which is not publicly browsable.

Hyva + Luma Ready

• Native Hyva templates built on Alpine.js with no jQuery or RequireJS.
• Native Luma templates using standard PHTML and vanilla JS.
• Theme is detected automatically through Panth\Core\Helper\Theme.

Compatibility

Installation

Composer Installation (Recommended)

composer require mage2kishan/module-order-attachments
bin/magento module:enable Panth_Core Panth_OrderAttachments
bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento setup:static-content:deploy -f
bin/magento cache:flush

Manual Installation via ZIP

1. Download the latest release from Packagist or from the product page.
2. Extract it to app/code/Panth/OrderAttachments/ in your Magento install.
3. Make sure Panth_Core (1.0.17 or later) is installed too, as it is a required dependency.
4. Run the commands above starting from bin/magento module:enable.

Verify Installation

bin/magento module:status Panth_OrderAttachments
# Expected: Module is enabled

After install, open:

Admin -> Stores -> Configuration -> Panth -> Order Attachments

Configuration

Go to Stores -> Configuration -> Panth -> Order Attachments.

Per-Product Control

Edit any product in the admin, find the Order Attachments attribute group, and set Allow Order Attachments (the panth_allow_order_attachment attribute) to Yes or No.

How It Works

1. Admin sets Allow Order Attachments to Yes on a product.
2. The customer visits the product page and sees the drag-and-drop upload widget.
3. The customer selects one or more files. Client-side and server-side validation check the extension, MIME type, and file size.
4. Files are stored in var/order_attachments/ with SHA-256 hashed filenames. The attachment is linked to the quote item.
5. Attachment cards appear in the cart, minicart, and checkout summary.
6. When the customer edits the cart item, they can add, replace, or remove attachments.
7. On order placement, an observer copies the attachments from the quote item to the order item and sets the order_id and order_item_id in the panth_order_attachment table.
8. The customer can see and download their uploaded files from My Account -> Orders -> View Order.
9. The admin manages all attachments from the dedicated grid and from the Order Attachments section on the admin order view page.

Admin Management

Dedicated Grid

Navigate to Panth Extensions -> Order Attachments -> Manage Attachments.

The grid shows:

• Thumbnail preview column for images, file-type badge for documents.
• Filename, product (linked), order ID (linked), customer email, file size, extension, status.
• Created and updated dates.
• Download action per row.
• Filters: order ID, customer email, SKU, date range, file type.

Order View Tab

Open any order in the admin. The Order Attachments section lists:

• Filename with a download link.
• Linked product name.
• File size and extension.
• Customer name and email.
• Customer note (if provided).
• Upload date.

FAQ

Does it work on Hyva themes?

Yes. Panth Order Attachments ships native Alpine.js templates for Hyva. The module reads the active theme through Panth_Core and loads the Hyva template automatically. The Luma vanilla-JS template is also included.

Can customers upload multiple files per product?

Yes. Set Maximum Files Per Item in the Upload Settings group. Each enabled product in the cart accepts up to that many files per line item.

What file types are allowed?

You configure a comma-separated allowlist in the Upload Settings. Common defaults: jpg, jpeg, png, gif, pdf, doc, docx, zip. You can add ai, psd, eps, svg, tif, xlsx, and others. Executable types like php, phtml, sh, and jsp are always blocked, even if you type them into the allowlist.

Where are the uploaded files stored?

In var/order_attachments/ with SHA-256 hashed filenames. The directory is not publicly browsable. Files are served only through the ownership-gated download controller, so customers can only download files tied to their own orders.

Can guests use Order Attachments?

Yes. Both guest and registered customer checkouts are supported. Guest sessions are tracked by session ID.

Will it break after a Magento upgrade?

The module uses standard Magento extension patterns, constructor dependency injection only, and no direct ObjectManager usage. It has been tested on Magento 2.4.4 to 2.4.8 with PHP 8.1 to 8.4.

Can the admin delete or download attachments after the order is placed?

Yes. Admins can download any attachment from the grid or the order view tab. Soft-delete is available from the admin grid. Customers cannot hard-delete files.

Does it work with Adobe Commerce Cloud?

Yes. Files are stored in the writable var/ directory, which persists across deploys on Adobe Commerce Cloud.

Does it support multi-store setups?

Yes. Configuration respects Magento's default, website, and store view scope. Attachments are stored per order item regardless of store view.

Support

Response time: 1-2 business days.

Need Custom Magento Development?

Looking for custom Magento module development, Hyva theme work, store migrations, or performance tuning? Get a free quote in 24 hours:

About Panth Infotech

Built and maintained by Kishan Savaliya (kishansavaliya.com), a Top Rated Plus Magento developer on Upwork with 10+ years of eCommerce experience.

Panth Infotech is a Magento 2 development agency that builds high quality, security focused extensions and themes for both Hyva and Luma storefronts. The extension suite covers SEO, performance, checkout, product presentation, customer engagement, and store management, with each module built to MEQP standards and tested across Magento 2.4.4 to 2.4.8.

Browse the full extension catalog on our Magento extensions page or on Packagist.

Quick Links

Ready to accept file uploads with your Magento 2 orders?

SEO Keywords: magento 2 order attachments, magento 2 file upload checkout, attach files to orders magento 2, magento 2 order item file upload, magento 2 checkout file upload extension, magento 2 order attachments extension, magento 2 print on demand file upload, magento 2 prescription upload, magento 2 personalised products upload, magento 2 artwork upload, magento 2 per product file upload, magento 2 multi file upload, magento 2 admin order attachment grid, magento 2 thumbnail preview upload, magento 2 file validation extension, magento 2 customer file upload, magento 2 b2b file upload, magento 2 hyva file upload, magento 2 luma file upload, alpine js order upload, magento 2 drag drop upload checkout, magento 2 attachment order item, magento 2.4.8 extension, php 8.4 magento module, mage2kishan order attachments, panth order attachments, panth infotech, hire magento developer, top rated plus upwork, kishan savaliya magento, custom magento development