E-commerce
March 25, 2025
When an order requires a file (logo for engraving, supporting document, PDF brief, retouching photo), the ideal experience remains in the native flow: checkout or customer account, without backup email or an unreliable external form. The interface extensions Shopify Checkout UI and Customer Account UI expose the DropZone component: a file drop area or file picker, aligned with the design system. This guide summarizes the role of the component, the technical flow through to storage in Shopify, the documented file-side limitations, and the security requirements recommended by OWASP. The following sections refer to the official documentation on shopify.dev and the Shopify Help Center (files). For business data, cross-reference our metafields and metaobjects guide.
Summary
What is the DropZone component?
The DropZone is a form component offered in Shopify interface extensions for checkout and customer accounts. It allows the buyer to add files by drag and drop or by selection through the browser's native dialog. The Checkout UI extensions documentation describes its properties (label, accepted types, multiple files, error state, etc.) in the form components section: see the DropZone (Checkout UI extensions, API 2025-04) entry.
The component handles interaction on the storefront side: it does not by itself replace file persistence or the association with the order. File storage and recording a reference (URL, identifier) are handled by a backend and the Admin APIs, in accordance with the GraphQL documentation on uploads.
Checkout UI, Customer Account UI and scope
The Checkout UI extensions are displayed in the checkout flow according to the extension targets allowed by Shopify (blocks, headers, etc., depending on your plan and configuration). The Customer Account UI extensions are displayed in the new customer account area. DropZone can be used in either context when your app needs it: the principle remains the same (file selection), but the targeting and deployment rules differ. Always check the API version and the list of available components for your extension target at development time.
E-commerce use cases
Customization : logos, print-ready visuals, vector files.
Verification : ID or supporting document when your legal process requires it (with GDPR framework and clear purpose).
Brief : PDF specifications for a service or custom order.
Instructions : document attached in addition to structured delivery instructions.
In all cases, the added value is the continuity of the journey : the customer understands what is expected, when, and in what format.
Architecture: from the interface to the stored file
A complete implementation combines four layers:
Layer | Role | Typical technology |
|---|---|---|
Interface | Selection, basic validation, UX | DropZone in the Checkout or Customer Account extension |
Transport | Secure file transfer to your server or orchestrated flow | HTTPS, called from a dedicated backend |
Shopify storage | Deposit of the file in the merchant's file space | Mutation |
Business linking | Attach the URL or identifier to the order or customer | Metafields, metaobjects depending on your model |
The mutation stagedUploadsCreate creates temporary and secure upload targets: this is the first step in the two-step upload process described by Shopify. The documentation states that this approach improves reliability for large files, media, and imports, and that the returned URL then serves as originalSource for mutations such as fileCreate after the file has actually been uploaded.
Implementation: technical steps
1. DropZone Interface
Configure the component with the documented properties: accepted types (MIME or extensions), multi-file handling if needed, clear labels, and explicit error messages. Provide visual feedback during upload (spinner, progress): a silent upload undermines trust.
2. Required backend
Calls to the Admin API (creating upload targets, file creation, writing metafields) must run on the server with protected access tokens. Never expose API secrets in the extension bundle rendered on the client.
3. Staged upload then fileCreate
Chain the steps: obtain the target via stagedUploadsCreate, upload the file to the provided URL with the authentication parameters, then create the file asset via fileCreate using resourceUrl as indicated in the mutation documentation.
4. Metafields
Store a stable reference (file URL, GID) on the order or customer depending on your business need, via the appropriate mutations. Document the schema for support teams.
For global tooling (CLI, previews), rely on the Shopify development resources.
Admin-side GraphQL flow details
After receiving the file on your server, the standard flow follows Shopify documentation: the stagedUploadsCreate mutation takes an input describing the file (resource, name, size, content type according to the required fields). The response provides an upload URL and parameters to include in the HTTP request to the temporary storage. Once the upload is complete, you use resourceUrl as originalSource in fileCreate to create the file asset that can be used in the admin. This two-step scheme exists precisely to make large files more reliable and secure the transfer.
The userErrors returned by the mutations must be logged on the server side and translated into a user-friendly message without leaking technical information. Plan for limited retries and a reasonable delay for large files to avoid blocking checkout sessions.
Checkout extension and customer account extension: nuances
Theme | Checkout UI | Customer Account UI |
|---|---|---|
Timing | During checkout | After account authentication |
Available data | Cart, line items, current order context | Customer profile, history depending on permissions |
UX constraint | Short time window, less tolerance for error | May allow resuming or completing later |
Typical use case | File required to complete | Updating documents on an open case |
The DropZone component follows the same paradigm; change the business context and the GraphQL objects you update afterward.
Sessions, secrets and Shopify best practices
Extensions run in a controlled environment: your calls to your backend must use authentication mechanisms provided by the platform (for example, exchanging session tokens according to the app model). Never store the Admin API key in version-controlled source code. Limit OAuth scopes to the strict minimum necessary (files, commands, metafields). Revoke and rotate secrets if a leak is suspected.
Sensitive data and compliance
Files may contain personal data or health data: minimization is essential (collect only what is necessary), as is a retention and deletion policy. OWASP also reminds us of the risks if files are then publicly accessible without control: exposure, illegal content, denial of service through repeated downloads. If you expose a URL, make sure it complies with your privacy policy and individuals' rights.
Observability and support
Plan correlation IDs between the storefront upload attempt and the entry in your server logs: when a customer contacts support, you can retrieve the failure without replaying the entire order. Store the file size, the declared type, the server-validated type, and the final status (success, rejection, timeout).
Limits and formats: what Shopify says
Even when the upload passes through your application, files ending up in the Shopify admin are subject to the Help Center rules. For generic files (excluding HTML) intended for download, the documentation indicates a maximum size of 20 MB and broad formats on paid plans, with restrictions on free trials. For images, the same 20 MB limit is indicated, with resolution and format constraints listed on the Upload and manage files page (file requirements section).
Your extension must display clear instructions (maximum size, formats) and reject out-of-scope files on the client side; server-side validation remains essential.
Additional sections
Upload security: OWASP principles
OWASP reminds us that uploads are an attack surface: fake files, malicious content, storage saturation. The recommended roadmap emphasizes a list of allowed extensions, input validation, and defense in depth.
"The application must be able to reject fictitious and malicious files in order to preserve the security of the application and its users."
OWASP File Upload Cheat Sheet (free translation)
To apply this concretely: an allowlist of extensions aligned with your business use case, server-side validation (size, actual type, file name), rate limiting, and a storage policy appropriate to the sensitivity of the documents (identity, health, etc.). The Content-Type announced by the browser is not proof: OWASP notes that it can be forged; it should not be enough on its own.
UX, mobile, and accessibility
MDN (web documentation) documents the behavior of the input type="file" element: the browser provides a file selection interface; the accept and multiple attributes help guide the user. On mobile, drag-and-drop is often secondary: the selection button and a clear label remain central.
Provide short messages if a file is rejected (type or size too large) and avoid blocking checkout without an alternative when the file is optional.
Limitations and points of attention
Extension surface: the bundle and allowed targets are constrained by Shopify rules; check compatibility with your plan and API version.
"Preview" functionality: a rich image preview may require additional development outside the default component.
Style: the rendering follows the extension design system; test on real themes.
Compliance: personal documents require a legal basis, a retention period, and controlled internal access.
Tests and production rollout
Test edge-case files (size near the limit, allowed and denied types).
Test on iOS and Android mobile devices: selection from the gallery, cloud files.
Check network error paths (timeout, retry).
Verify that files appear correctly in the admin and that metafields are readable by support.
Developer checklist before going live
Checkout UI / Customer Account UI API version fixed and tested on a development store.
Minimal OAuth scopes validated in code review.
Light load tests on
stagedUploadsCreate: no infinite retry loop on the client side.Server-side file naming policy (UUID or prefix) to avoid collisions and directory traversal.
Legal notice / privacy page up to date if collecting identity documents.
Alternatives if the DropZone is not enough
For very large volumes, formats outside the Shopify allowlist, or an external processing pipeline (virus scan, conversion), you can delegate storage to an object storage provider while keeping a UX entry point in the extension: the extension then sends a signed token to your API, which orchestrates the remote upload and stores only a reference or identifier in Shopify in a metafield. This model makes the architecture more complex but respects compliance or performance constraints.
For purely conversational needs without a structured file, a chatbot can sometimes be enough to qualify the request before redirecting to a flow with an attachment.
Best practices and common mistakes
Best practices
Restrict
acceptto the strict minimum needed to reduce risk and noise.Validate each file on the server side before business processing.
Log upload errors without exposing secrets in client-facing messages.
Common mistakes
Error | Risk | Fix |
|---|---|---|
Admin secrets in the front end | Store compromise | Dedicated backend, environment variables |
Relying only on the client MIME type | Malicious upload | Server validation, allowlist |
No size limit | DoS / costs | Alignment with the Help Center + application limit |
Benefits for your store
Unified flow: less friction than an external form.
Traceability: file linked to the order or customer in Shopify.
Scalability: you stay within the ecosystem of extensions and documented APIs.
The conversion gain depends on your offer and the clarity of the instructions: avoid generic numerical promises without A/B testing on your audience.
Complete with a chatbot
Attachments meet a transactional need; an AI chatbot like Qstomy can help before checkout to explain accepted formats, timelines, or customization options, and reduce drop-offs caused by uncertainty. Discover the AI chatbot integration on Shopify and our e-commerce chatbot guide.
Does the Shopify plan change file rules?
Accepted formats on trial and paid plans can differ: the Help Center describes restrictions on trials and email verification for certain types. Check the up-to-date French page before promising formats to your customers.
What should I do if fileCreate fails after upload?
Check that the resourceUrl really matches the uploaded file, that the announced size was correct, and that the type is supported. Log the userErrors message and provide a generic message on the storefront.
Multiple files on the same order line
Plan for a clear data model: a list of file IDs in a JSON metafield, or multiple named metafields, and test the practical UX limit (upload time, abandonment).
Summary
The DropZone in Shopify extensions serves as a file collection point in checkout or customer accounts. It must be combined with a backend using the Admin mutations stagedUploadsCreate and fileCreate, then with metafields to link the resource to the order or customer. Respect the Help Center limits (sizes and formats), apply OWASP best practices, and test on mobile. Keep your implementation aligned with the documented API version. Document the tested API version and build identifiers in your repository to make later audits and minor updates easier. shopify.dev.
FAQ
How can I limit file types?
Use the DropZone accept property (MIME types or extensions) and complement it with server-side validation that matches the business allowlist.
Do I need a backend?
Yes for Admin calls and secrets: the extension must not include store access tokens.
What is the maximum size?
For generic files and images, the Help Center commonly indicates a 20 MB limit; check the up-to-date page for your context.
Is drag-and-drop mandatory?
No: native file selection remains the main option on mobile; provide a clear button.
Identity data
Provide information about purpose, retention period, and access; GDPR compliance is a prerequisite independent of the component.
Go further
March 25, 2025
