Export and Import Option Sets

This guide explains how to use the Import/Export page (Option sets → Import/Export) to bulk-export your option sets to a CSV file, edit them offline, and re-import them — including exactly what to put in every column.

It's written directly from the app's own validation code, so the rules, limits, and error messages below match what you'll actually see in the product.

Import / Export is available on the Advanced plan and above. See Plans and feature availability.

1. Overview

The Import/Export page has two independent tools:

Tool	What it does
Export	Downloads your option sets (all of them, or a hand-picked subset) as one CSV file.
Import	Uploads a CSV file, checks it, shows you a review screen, and creates/updates option sets from it.

The most reliable way to build an import file is to export first, then edit the CSV, rather than writing one from scratch. That way the header row, column order, and the exact JSON shape of the advanced fields are guaranteed correct.

2. Exporting option sets

Click Export on the Export Option sets card.
Choose a scope:

All option sets — everything in the store.
Selected option sets — check the ones you want, click Select, then Export option sets.

The file downloads as a single .csv.

3. Importing option sets — step by step

Prepare your file

Download the sample template or start from a file you just exported. Edit it in Excel/Google Sheets/a text editor, keeping the header row untouched.

Hard limits, checked immediately on upload, before anything else happens:

Limit	Value
File type	`.csv` only
Max file size	20 MB
Max data rows	50,000
Header row	Must exactly match the 44 expected column names, in order
Content	The file can't be effectively empty

Any of these fail instantly with an "Import failed" error — no job is created, nothing is stored.

Upload and Import

Click Import → Add file (or drag-and-drop) → Upload and Import. Only one import can run per store at a time; starting a new one while another is mid-review replaces it.

Validating and Review

If errors were found, it will show one of these messages:

🔴 "N validation errors found" — hard errors: a required field is missing, or a field's value/format is wrong. This blocks the import entirely — nothing can be imported until the file is fixed and re-uploaded.
🟡 "N references not found in your store" — warnings: a field's format is fine, but it points at something that isn't a real product/customer/tag/variant on your store. This does not block the import — click Continue import and the file imports normally, with that specific setting removed / falling back to its default.
- Click Continue import to actually write the option sets to your store

Complete the import

🟢 "Import completed successfully" banner shows how many option sets were imported.

💡Bonus: looking up variant IDs

The search box under the Import button (Search variant ID) opens a product/variant search-and-copy tool — use it to find the exact Shopify variant IDs to paste into Products (product variant: ...) or Upsell_product_ID.

4. How rows fit together (the data model)

Every CSV row is one of four types:

Row type	Fills in
Set's first row	`Option_set_id`, `Option_set_name`, `Priority`, `Status`, `Products`, `Exclude_products`, `Customers` — plus its own option data
Later row, same set	`Option_set_id` only (same value); the rest stay blank (= "same as first row")
Option Group row	`Option_type` = `Option Group`; groups other options via `Option_in_group` (one name per line) — doesn't collect input itself
Value row	One row per choice, for choice-list types (Checkbox, Dropdown, Radio Button, Swatch, Button, Switch, Dropdown w/ Thumbnail); `Option_id` repeats, `Option_type`/`Option_name` stay blank

5. Full field reference

This section cross-checks the app's actual validation code against the Field sheet in the Excel file you sent. Every column gets: whether it's required, which row(s) need it, and exactly what to type. Where the Excel doc and the current code disagree, that's called out explicitly rather than silently picking one.

A cell you leave blank on a required-on-first-row field is a hard error only on that first row — the same blank cell on a continuation/value row is completely normal.

#	Field	Required?	Scope	Allowed values	Example
1	`Option_set_id`	Required, every row	Every row of the set	Number	`1`
2	`Option_set_name`	Required (1st row)	Set, first row only	Free text	`Custom T-shirt`
3	`Priority`	Optional	Set, first row only	`0`–`99`; blank = `0`	`0`
4	`Status`	Optional (1st row)	Set, first row only	`Live` / `Inactive`	`Live`
5	`Products`	Optional	Set, first row only	See §7.1	`collections: New arrivals`
6	`Exclude_products`	Optional	Set, first row only	See §7.1	`tags: discontinued`
7	`Customers`	Optional	Set, first row only	See §7.1	`registered`
8	`Option_id`	Required, every row	Every row of the option	Number	`5`
9	`Option_type`	Required (1st row)	Option, first row only	See §6	`Swatch`
10	`Option_name (Label_product)`	Required (1st row)	Option, first row only	Free text	`Choose Your Color`
11	`Label_cart`	Optional	Option, first row only	Free text	`Color`
12	`Hide_label`	Optional	Option, first row only	`Yes` / `No`	`No`
13	`Required`	Optional	Option, first row only	`Yes` / `No`	`Yes`
14	`Hide_option`	Optional	Option's 1st row / Group row	`Yes` / `No`	`No`
15	`Column_width`	Recommended	Option, first row only	`100`/`75`/`66`/`50`/`33`/`25`	`33`
16	`Option_value`	Required for choice lists	Every value row	Free text	`Red`
17	`Helptext_option_value`	Optional	Every value row	Free text	`Good choice`
18	`SKU_value`	Optional	Every value row	Free text	`ABC`
19	`Swatch_value`	Required for Swatch etc.	Every value row	Hex or image CDN URL	`#ffffff`
20	`Swatch_title_display_type`	Optional, Swatch only	Option's first value row	See §5.3	`None`
21	`Option_price_type`	Optional	Value rows	`Extra fee` / `Upsell product`	`Extra fee`
22	`Option_price`	Optional	Value rows	Number	`100`
23	`Upsell_product_ID`	Optional	Value rows	Product/variant ID	`['123456789']`
24	`Group_display_type`	Optional	Option Group row	`Expand` / `Collapse`	`Expand`
25	`Option_in_group`	Optional	Option Group row	Names, one per line	`Color`
26	`Visibility (Conditional_logic)`	Optional	Option, first row only	JSON — §7.2	see §7.2
27	`Min_selections_characters`	Optional	Option, first row only	Number	`1`
28	`Max_selections_characters`	Optional	Option, first row only	Number > Min	`2`
29	`Enable_quantity`	Optional	Option, first row only	`Yes` / `No`	`Yes`
30	`Min_quantity`	Optional	Option, first row only	Number	`1`
31	`Max_quantity`	Optional	Option, first row only	Number > Min	`10`
32	`Dropdown_search_bar`	Optional	Option, first row only	`Yes` / `No`	`No`
33	`Placeholder_text`	Optional	Option, first row only	Free text	`Enter text here`
34	`Default_value`	Optional	Option, first row only	Text, or `Yes` per pre-selected value	—
35	`Helptext_content`	Optional	Option, first row only	Free text	`Easy to setup`
36	`Helptext_position`	Optional	Option, first row only	See §5.3	`Tooltip`
37	`Option_value_orientation`	Optional	Option, first row only	`Horizontal` / `Vertical`	`Horizontal`
38	`Rich_text_value`	Required for static text	Option, first row only	HTML	`<p>...</p>`
39	`Label_on_popup`	Optional, Popup only	Option, first row only	Free text	`Read more`
40	`Font_picker_settings`	Required for Font Picker	Option, first row only	JSON — §7.3	see §7.3
41	`File_upload_settings`	Required for File Upload	Option, first row only	JSON — §7.4	see §7.4
42	`Date_time_settings`	Required for Date & Time	Option, first row only	JSON — §7.5	see §7.5
43	`Live_mockup`	Optional, advanced	Option, first row only	JSON — §7.6	see §7.6
44	`Background`	Optional, advanced	Option, first row only	JSON — §7.6	see §7.6

6. Option types reference

Option type	Has a value list?	Notes
`Text Box`	No	Single row. Uses `Placeholder_text`, `Default_value`, `Min/Max_selections_characters`.
`Number Field`	No	Single row. Uses `Placeholder_text`, `Default_value`, `Min/Max_selections_characters`.
`Email`	No	Single row. Uses `Placeholder_text`, `Default_value`, `Min/Max_selections_characters`.
`Text Area`	No	Single row. Uses Single row. Uses `Placeholder_text`, `Default_value`, `Min/Max_selections_characters`.
`Checkbox`	Yes	One row per checkbox choice.
`Dropdown Menu`	Yes	One row per menu item.
`Dropdown Menu With Thumbnail`	Yes	One row per item; `Swatch_value` holds the thumbnail image URL.
`Radio Button`	Yes	One row per choice.
`Swatch`	Yes	One row per swatch; `Swatch_value` is a hex color or image; `Swatch_title_display_type` controls label placement.
`Button`	Yes	One row per button choice.
`Switch`	Yes	One row per switch choice.
`File Upload`	No	Single row. Requires `File_upload_settings`.
`Date & Time`	No	Single row. Requires `Date_time_settings`.
`Color Picker`	No	Single row — lets the customer pick any custom color.
`Font Picker`	No	Single row. Requires `Font_picker_settings`; can apply to other text options via that JSON's `listOptionApplied`.
`Paragraph`	No	Single row. Content goes in `Rich_text_value`.
`Heading`	No	Single row. Content goes in `Rich_text_value`.
`Divider`	No	Single row. Purely visual; html goes in `Rich_text_value`
`Pop-up Modal`	No	Single row. Content in `Rich_text_value`, trigger label in `Label_on_popup`.
`Option Group`	—	Bundles other options together. Uses `Group_display_type` + `Option_in_group`.

7. Special field formats

7.1 `Products` / `Exclude_products` / `Customers`

These three columns use short text prefixes to say which kind of condition you mean. Everything after the prefix is separated with ; (semicolons) — except a plain product-title list, which can use newlines or commas.

Products (who this option set applies to)

Meaning	What to type
All products	leave blank, or `all`
Specific products	just the product title(s), one per line: `Custom T-shirt`⏎`Custom Phone Case`
Specific collections	`collections: Collection A; Collection B`
Products with a tag	`tags: freeship; sale`
Specific product variants (by ID)	`product variant: 41816231542953; 44240103014715`

Customers (who sees this option set)

Meaning	What to type
All customers	leave blank, or `all`
Registered / logged-in customers	`registered`
Guests (no account)	`without accounts`
Specific customers, by email	`specific:` `a@gmail.com;` `b@gmail.com`
Customers with a tag	`tags: vip; wholesale`

Exclude_products (removes products from the match above)

Meaning	What to type
None	leave blank, or `None`
By products tag	`tags: discontinued; clearance`

Currently Exclude_products only recognizes the tags: format (or blank/None). Typing a plain product title here has no effect — if you need to exclude specific products by name, use a product tag instead.

A reference that doesn't match anything on your store (a typo'd collection name, an email that isn't a customer) shows up as a warning, not a hard error — the field is simply cleared if you continue.

7.2 `Visibility (Conditional_logic)`

Shows or hides this option depending on the value of another option in the same set.

{
  "action": "show",
  "match": "all",
  "conditions": [
    { "option_label": "Color", "operator": "IS", "value": "Red" },
    { "option_label": "Engraving Text", "operator": "CONTAINS", "value": "cat" }
  ]
}

Key	Values
`action`	`show` / `hide`
`match`	`any` (at least one condition must be true) / `all` (every condition must be true)
`conditions[].option_label`	Must exactly match another option's `Option_name (Label_product)` in the same option set
`conditions[].operator`	`IS`, `IS NOT`, `LESS_THAN`, `GREATER_THAN`, `CONTAINS`, `DOES NOT CONTAIN`
`conditions[].value`	Must match one of the referenced option's real values (for choice-list types)

Requirements: the option set needs at least 2 options for conditional logic to make sense, and every option_label must reference a real option that already exists in that same set. Anything malformed (bad JSON, an unrecognized action/match, a missing key) is treated as a warning — the row still imports, this field is simply dropped.

7.3 `Font_picker_settings`

{
  "typeFontSelection": "specific",
  "font_picker_values": ["ABeeZee", "AR One Sans", "Abel"],
  "displayFontPicker": "dropdown",
  "listOptionApplied": ["Enter custom text"]
}

Key	Values
`typeFontSelection`	`all` / `specific`
`font_picker_values`	Array of font name strings
`displayFontPicker`	`dropdown` / `button_horizontal` / `button_vertical`
`listOptionApplied`	Array of other options' `Option_name (Label_product)` this font choice should apply to

Only font_picker_values is strictly required; the rest fall back to sensible defaults if omitted or malformed.

7.4 `File_upload_settings`

{ "file_type": "custom", "custom_file_type": "png, img", "max_files": 5 }

Key	Values
`file_type`	`all` / `image` / `document` / `custom`
`custom_file_type`	Comma-separated extensions, only meaningful when `file_type` is `custom` — otherwise leave as `""` (the key must still be present)
`max_files`	Number

7.5 `Date_time_settings`

{
  "date_time_mode": "date_picker",
  "date_time_config": [
    { "allDay": true, "name": "Monday", "selected": true, "timeEnd": "23:59", "timeStart": "00:00" },
    { "allDay": true, "name": "Tuesday", "selected": true, "timeEnd": "23:59", "timeStart": "00:00" },
    { "allDay": true, "name": "Wednesday", "selected": true, "timeEnd": "23:59", "timeStart": "00:00" },
    { "allDay": true, "name": "Thursday", "selected": true, "timeEnd": "23:59", "timeStart": "00:00" },
    { "allDay": false, "name": "Friday", "selected": true, "timeEnd": "20:59", "timeStart": "00:00" },
    { "allDay": false, "name": "Saturday", "selected": true, "timeEnd": "20:59", "timeStart": "00:00" },
    { "allDay": false, "name": "Sunday", "selected": true, "timeEnd": "20:59", "timeStart": "00:00" }
  ],
  "display_date_time_type": 1,
  "time_format": 0,
  "overall_format": 1,
  "disable_past_date": 3,
  "disable_past_date_type": 3,
  "disable_specific_date": ["04 Jun 2026", "13 Jun 2026"],
  "disable_date_range": ["10 Jun 2026 to 12 Jun 2026"],
  "disable_all_past_date": 1
}

The four keys date_time_mode, display_date_time_type, time_format, overall_format must be present.
date_time_mode is date_picker or date_range.
The other numeric codes (which weekday/format/deactivation option each number means) mirror whatever the Date & Time option editor's UI currently offers — the safest way to get these exactly right is to configure one Date & Time option in the editor, export that option set, and copy its Date_time_settings cell as your template.

7.6 `Live_mockup` / `Background`

Both are advanced "live preview" settings tied to the option editor's mockup feature.

Live_mockup requires the top-level keys enable, size_config, pos_config, transforms.
Background requires type, overlay_mode, width, height (type: MAIN_PRODUCT / CUSTOM; overlay_mode: FIRST_IMAGE_FROM_START / OVERLAY_AFTER_FILL_VALUE).

These have deep nested shapes that aren't meant to be hand-written. Configure the live preview in the option editor once, export that option set, and reuse its Live_mockup/Background cells verbatim rather than writing them from scratch.

8. Common errors & how to fix them

These are the exact messages you'll see on the review screen.

Hard errors (row is skipped until fixed)

Message	What it means / how to fix
Required field is missing	A required column (see the Required column in §5) is blank on a row where it must be filled in
Unknown option type "…"	`Option_type` doesn't match any value in §6 — check spelling/casing
Invalid value "…" (Status)	`Status` must be `Live` or `Inactive`
Expected "Yes" or "No", got "…"	A Yes/No column has something else in it
Expected a number, got "…"	A numeric column has non-numeric text in it
Invalid JSON	A JSON column (`Font_picker_settings`, `File_upload_settings`, `Date_time_settings`, `Live_mockup`, `Background`, `Visibility (Conditional_logic)`) isn't valid JSON at all — check for missing quotes/commas/brackets
Expected a JSON object	The JSON parsed, but isn't an object (e.g. it's an array or a bare string)
Missing required keys: …	The JSON object is missing one of the required keys listed in §7
"conditions" must be an array	`Visibility (Conditional_logic)`'s `conditions` key isn't a list
Each condition must have "option_label", "operator", and "value"	One of the condition objects is missing a required key
Invalid price type "…"	`Option_price_type` must be `Extra fee` or `Upsell product`
Invalid swatch title display type / group display type / helptext position	The cell doesn't match one of that field's allowed values — see §5 for the exact list
Duplicate option name "…" in option set "…"	Two options in the same set share the same `Option_name (Label_product)`
Duplicate Option_id "…" in option set "…"	Two options in the same set share the same `Option_id` — only the first is kept
Duplicate Option_set_id "…" in the file	The same `Option_set_id` appears in more than one non-contiguous block — they're merged into the first occurrence
Option_set_id "…" doesn't match this option set — moved / kept in this set	An option row's `Option_set_id` disagrees with the set it's positioned under — the importer resolves it by ID where possible
Max_quantity must be greater than Min_quantity	Fix the two values so max > min (both are otherwise dropped)
Max_selections_characters must be greater than Min_selections_characters	Same idea, for character limits
Conditional logic requires at least 2 options in the set	Add another option to the set, or remove the `Visibility` rule
Conditional logic references option "…", which doesn't exist in this set	Fix `option_label` to match a real option's name in the same set
Conditional logic value "…" doesn't match any value of option "…"	Fix `value` to match one of that option's real choice values
Conditional logic action/match must be "Show"/"Hide" or "Any"/"All"	Fix the `action`/`match` key's value

Warnings (row still imports; only the flagged cell is cleared)

Banner	Meaning
Products / Collections / Variants / Customers / Product tags / Customer tags not found	The named item doesn't exist on this store — double-check spelling, or that it's the right store
`Swatch_value` images unreachable	The image URL couldn't be fetched — check the link is public and correct
Invalid column width (falls back to 100)	`Column_width` wasn't one of the six allowed values
Invalid priority (falls back to 0)	`Priority` wasn't a whole number 0–99
Invalid font picker display/selection mode (reset to default)	`Font_picker_settings`'s `displayFontPicker`/`typeFontSelection` had an unrecognized value

9. Tips & best practices

Start from a real file. Use the sample template or (better) a file you just exported — don't build the header row from scratch.
Don't touch the header row. Column names and order must match exactly.
Multi-line cells use in-cell newlines, not new spreadsheet rows. In Excel/Google Sheets, press Alt+Enter (Windows) or ⌥+Return (Mac) inside a cell for Products (specific-product lists) or Option_in_group.
Option_in_group names must match exactly. Case and spacing matter — copy the option's Option_name (Label_product) verbatim.
For the advanced JSON fields (Font_picker_settings, File_upload_settings, Date_time_settings, Live_mockup, Background), configure one real example in the option editor UI and export it — copy that cell rather than hand-writing the JSON.
Test with a small file first, especially the first time you import into a store — a 2–3 row file surfaces formatting mistakes faster than a 500-row one.
It's safe to leave and come back. The review screen persists for a while and the job itself lives 24 hours server-side — but if you sit on the review screen too long without confirming or cancelling, it will expire.

10. Limits at a glance

Limit	Value
Accepted file type	`.csv`
Max file size	20 MB
Max data rows	50,000
Concurrent imports per store	1
Job lifetime	24 hours

Updated on: 27/09/2026

Was this article helpful?

Thank you!

Export and Import Option Sets

Export and Import Option Sets

1. Overview

2. Exporting option sets

3. Importing option sets — step by step

💡Bonus: looking up variant IDs

4. How rows fit together (the data model)

5. Full field reference

6. Option types reference

7. Special field formats

7.1 Products / Exclude_products / Customers

7.2 Visibility (Conditional_logic)

7.3 Font_picker_settings

7.4 File_upload_settings

7.5 Date_time_settings

7.6 Live_mockup / Background

8. Common errors & how to fix them

Hard errors (row is skipped until fixed)

Warnings (row still imports; only the flagged cell is cleared)

9. Tips & best practices

10. Limits at a glance

7.1 `Products` / `Exclude_products` / `Customers`

7.2 `Visibility (Conditional_logic)`

7.3 `Font_picker_settings`

7.4 `File_upload_settings`

7.5 `Date_time_settings`

7.6 `Live_mockup` / `Background`