> For the complete documentation index, see [llms.txt](https://docs.optis.me/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.optis.me/product-options/advanced-setup/export-and-import-option-sets.md).

# 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.

***

### 1. Overview

The Import/Export page has two independent tools:

<table><thead><tr><th width="106.23828125">Tool</th><th>What it does</th></tr></thead><tbody><tr><td><strong>Export</strong></td><td>Downloads your option sets (all of them, or a hand-picked subset) as one CSV file.</td></tr><tr><td><strong>Import</strong></td><td>Uploads a CSV file, checks it, shows you a review screen, and creates/updates option sets from it.</td></tr></tbody></table>

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

{% stepper %}
{% step %}
Click **Export** on the Export Option sets card.
{% endstep %}

{% step %}
Choose a scope:

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

<figure><img src="https://1821185975-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FRFiuDpHWm2HwzxPH4lfM%2Fuploads%2FOdP72V92QhhAU5BfeSok%2Fimage.png?alt=media&amp;token=dc1d04e3-95fa-442f-bfe7-3de442e4ace7" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}
The file downloads as a single `.csv`.
{% endstep %}
{% endstepper %}

***

### 3. Importing option sets — step by step

{% stepper %}
{% 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:**

<table><thead><tr><th width="177.69140625">Limit</th><th width="556.30859375">Value</th></tr></thead><tbody><tr><td>File type</td><td><code>.csv</code> only</td></tr><tr><td>Max file size</td><td>20 MB</td></tr><tr><td>Max data rows</td><td>50,000</td></tr><tr><td>Header row</td><td>Must exactly match the 44 expected column names, in order</td></tr><tr><td>Content</td><td>The file can't be effectively empty</td></tr></tbody></table>

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

{% step %}

#### 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.

<figure><img src="https://1821185975-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FRFiuDpHWm2HwzxPH4lfM%2Fuploads%2FyzD8SenyuayavDufw57R%2Fimage.png?alt=media&amp;token=474eab29-69b9-44c8-9184-12239d491670" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}

#### Validating and Review&#x20;

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
    {% endstep %}

{% step %}

#### Complete the import

🟢 **"Import completed successfully"** banner shows how many option sets were imported.&#x20;
{% endstep %}
{% endstepper %}

#### 💡Bonus: looking up variant IDs

<figure><img src="https://1821185975-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FRFiuDpHWm2HwzxPH4lfM%2Fuploads%2FOOzBVteHjP08zTvYBoew%2Fimage.png?alt=media&amp;token=6db56d3a-26f6-48aa-8797-e1c436653142" alt=""><figcaption></figcaption></figure>

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:

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

***

### 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.

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

***

### 6. Option types reference

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

***

### 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)

<table><thead><tr><th width="272.83984375">Meaning</th><th>What to type</th></tr></thead><tbody><tr><td>All products</td><td>leave blank, or <code>all</code></td></tr><tr><td>Specific products</td><td>just the product title(s), one per line: <code>Custom T-shirt</code>⏎<code>Custom Phone Case</code></td></tr><tr><td>Specific collections</td><td><code>collections: Collection A; Collection B</code></td></tr><tr><td>Products with a tag</td><td><code>tags: freeship; sale</code></td></tr><tr><td>Specific product variants (by ID)</td><td><code>product variant: 41816231542953; 44240103014715</code></td></tr></tbody></table>

**`Customers`** (who sees this option set)

<table><thead><tr><th width="279.64453125">Meaning</th><th>What to type</th></tr></thead><tbody><tr><td>All customers</td><td>leave blank, or <code>all</code></td></tr><tr><td>Registered / logged-in customers</td><td><code>registered</code></td></tr><tr><td>Guests (no account)</td><td><code>without accounts</code></td></tr><tr><td>Specific customers, by email</td><td><code>specific: a@gmail.com; b@gmail.com</code></td></tr><tr><td>Customers with a tag</td><td><code>tags: vip; wholesale</code></td></tr></tbody></table>

**`Exclude_products`** (removes products from the match above)

<table><thead><tr><th width="284.3671875">Meaning</th><th>What to type</th></tr></thead><tbody><tr><td>None</td><td>leave blank, or <code>None</code></td></tr><tr><td>By products tag</td><td><code>tags: discontinued; clearance</code></td></tr></tbody></table>

> 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*.

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

<table><thead><tr><th width="267.4921875">Key</th><th>Values</th></tr></thead><tbody><tr><td><code>action</code></td><td><code>show</code> / <code>hide</code></td></tr><tr><td><code>match</code></td><td><code>any</code> (at least one condition must be true) / <code>all</code> (every condition must be true)</td></tr><tr><td><code>conditions[].option_label</code></td><td>Must exactly match another option's <code>Option_name (Label_product)</code> <strong>in the same option set</strong></td></tr><tr><td><code>conditions[].operator</code></td><td><code>IS</code>, <code>IS NOT</code>, <code>LESS_THAN</code>, <code>GREATER_THAN</code>, <code>CONTAINS</code>, <code>DOES NOT CONTAIN</code></td></tr><tr><td><code>conditions[].value</code></td><td>Must match one of the referenced option's real values (for choice-list types)</td></tr></tbody></table>

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`

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

<table><thead><tr><th width="293.65625">Key</th><th>Values</th></tr></thead><tbody><tr><td><code>typeFontSelection</code></td><td><code>all</code> / <code>specific</code></td></tr><tr><td><code>font_picker_values</code></td><td>Array of font name strings</td></tr><tr><td><code>displayFontPicker</code></td><td><code>dropdown</code> / <code>button_horizontal</code> / <code>button_vertical</code></td></tr><tr><td><code>listOptionApplied</code></td><td>Array of other options' <code>Option_name (Label_product)</code> this font choice should apply to</td></tr></tbody></table>

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

#### 7.4 `File_upload_settings`

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

<table><thead><tr><th width="257.94140625">Key</th><th>Values</th></tr></thead><tbody><tr><td><code>file_type</code></td><td><code>all</code> / <code>image</code> / <code>document</code> / <code>custom</code></td></tr><tr><td><code>custom_file_type</code></td><td>Comma-separated extensions, only meaningful when <code>file_type</code> is <code>custom</code> — otherwise leave as <code>""</code> (the key must still be present)</td></tr><tr><td><code>max_files</code></td><td>Number</td></tr></tbody></table>

#### 7.5 `Date_time_settings`

```json
{
  "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.&#x20;
* `date_time_mode` is `date_picker` or `date_range`.&#x20;
* 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)

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

#### 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 <kbd>Alt</kbd>+<kbd>Enter</kbd> (Windows) or <kbd>⌥</kbd>+<kbd>Return</kbd> (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 |
|                              |          |