What bulk mapping does
Alva Digital Downloads links files that are already in storage to Shopify products from a single CSV. Open the Products page and click the Bulk Product-File Mapping secondary action. The screen is available on paid plans only — it is disabled on the Free plan.
What the CSV needs
The parser reads the header row and matches columns by name, case-insensitively. It requires one PRODUCT_ID column and at least one FILE_1 or LINK_1 column. Variant columns are optional. Column order does not matter, and you can add as many FILE_, LINK_ and VARIANT_ columns as you need.
- PRODUCT_ID — the Shopify product ID. Use the bare number (
1234567890) or the fullgid://shopify/Product/1234567890form. - FILE_1, FILE_2, … — each holds a file's title in Alva storage, optionally prefixed with
@(the@is stripped). - VARIANT_1, VARIANT_2, … — optional Shopify variant IDs. Leave them out to map to the default variant across the whole product.
- LINK_1, LINK_2, … — each holds the title of a saved link, using the same optional
@prefix. Link titles must be unique: if two of your links share a title, that row is rejected rather than guessing which one you meant.
Every row needs at least one file or one link. A row may carry only LINK_ columns, which creates a link-only product with no files attached — the same thing you get from the Links selector on a single product.
How to bulk-map files
1. Open the bulk mapping screen
On the Products page, click Bulk Product-File Mapping. The page opens with an instructions card — including a worked example CSV — and a drag-and-drop uploader. There is no downloadable template; copy the example layout into your spreadsheet.
2. Build and save the CSV
Put one product per row. Fill PRODUCT_ID with the Shopify ID and each FILE_ column with a file title. A bare row of 123456789,,,,@User Manual,, maps one file to a product's default variant; leaving the file columns empty and filling LINK_1 instead maps a link on its own. Save the sheet as .csv.
The Bulk Product-File Mapping preview table after a CSV upload. Show the five columns — File, Links, Product, Variants, Status — with 3–4 sample rows: green "success" badges, one red "error" row, one link-only row with an em-dash in the File column, and one product carrying an "Existing" badge. Use placeholder product names, no real customer data.
3. Upload and review the preview
Drop the file into the uploader. Alva checks each file title against storage and validates the product and variant IDs against Shopify. The preview lists every row with a Status badge — success, error, or pending — and flags products that already have mappings with an Existing badge.
4. Process the mappings
Click Process CSV. Valid rows save as product mappings and errored rows are skipped. If more than 30% of rows are invalid, Alva blocks the run. Below that threshold, a confirmation dialog tells you how many rows will be skipped before it proceeds.
5. Verify coverage
After a successful run, click View Products to return to the Products list. Each product shows its attachment count, so you can scan for anything still showing zero files. Fix those rows and re-run them with Retry failed mappings.
Frequently asked questions
Open the product in Shopify admin and copy the numeric ID at the end of the URL, like 1234567890. Alva accepts that bare number or the full gid://shopify/Product/1234567890 form in the PRODUCT_ID column.
No. The bulk mapping screen shows a worked example CSV inside the instructions card. Copy that layout into your spreadsheet — a PRODUCT_ID column plus FILE_1, FILE_2 and LINK_1 columns — rather than downloading a template file.
By the file's title in Alva storage, matched case-insensitively. You can prefix the title with an @ symbol, which Alva strips. The file must already be uploaded — bulk mapping links existing files, it does not upload them.
Errored rows are skipped and the valid rows still save. If more than 30 percent of rows are invalid, Alva blocks the whole run. Below that, a confirmation modal warns you which rows will be skipped before processing.
Add VARIANT_1, VARIANT_2 columns and put a Shopify variant ID in each. Rows with no variant columns map to the default variant and apply to the whole product. There is no limit on the number of variant columns.
See also
Was this helpful?
Last updated 2026-06-01