Import file reference

This is the field-by-field reference for Optionfier's import/export format: every Excel column, its JSON equivalent, accepted values, and what happens when you leave a cell blank. It assumes you've already read Importing and Exporting on the main docs page. If you're just backing up or moving your configuration between shops, start there instead.

Excel columns and JSON fields hold the same data; only the naming convention differs (column title vs. camelCase field). Leave an optional cell blank (or omit the field from JSON) to skip it:

On a create row, the default in the table below applies.
On a MERGE update row, the existing value is preserved (see What Stays the Same on Update).

"Required" means the field must be present on create rows; required fields on MERGE updates still fall back to the matched row's existing value if the file leaves them blank.

File-level Fields (JSON only)

Excel carries this information implicitly (shop and timestamp come from the workbook metadata on export). JSON has it as three top-level fields.

JSON field	Accepted values	Default	Notes
`version`	`1`	N/A	Schema version. Always `1` today.
`exportedAt`	ISO 8601 timestamp	N/A	When the file was exported. Informational.
`shopDomain`	`your-store.myshopify.com`	N/A	Source shop. Informational: the importer writes into the current session's shop regardless.
`groups`	array of option sets	`[]`	The root option-set array.

Option set fields

Each option-set row starts a new option set.

XLSX Column	JSON field	Accepted values	Default on create	Notes
`Group Handle`	`handle`	kebab-case slug, unique per shop	required	The anchor for MERGE matching. Handles are unique per shop.
`Command`	`command`	`MERGE`, `NEW`, or blank	`MERGE`	Case-insensitive. Any unknown value is treated as `MERGE`.
`Group Name`	`name`	any text	the handle, if blank	Merchant-facing display name.
`Product ID`	`productId`	Shopify product GID (e.g. `gid://shopify/Product/123`)	N/A	Connects the option set to a product. The importer prefers GID over handle when both are set.
`Product Handle`	`productHandle`	Shopify product handle (e.g. `custom-tshirt`)	N/A	Cross-store portability: used as a fallback when the GID doesn't resolve in this shop.
`Group Enabled`	`enabled`	`true`, `false`	`true`	`false` imports the option set as draft (won't render on the storefront).
`Group Position`	`position`	number	`1.0`	Display order on the main admin list.
`Inventory Engine`	`inventoryEngine`	`NATIVE_BUNDLES`, `INVENTORY_ONLY`	`NATIVE_BUNDLES`	The legacy value `LINE_ITEM_PROPERTIES` is still accepted so older files import: it is converted to `NATIVE_BUNDLES` with every option set in the group set to Text on order. See How Options Appear, and Who Tracks Inventory.
`Include Parent In Bundle`	`includeParentInBundle`	`true`, `false`	`false`	Only honoured when `Inventory Engine` is `NATIVE_BUNDLES`.
`Sold Out Entire Group`	`soldOutEntireGroup`	`true`, `false`	`true`	Disable add-to-cart when any option is fully sold out. A blank cell on a create row gets the database default, `true`; option sets created in the admin start at `false`.
`Derive Parent Inventory`	`deriveParentInventory`	`true`, `false`	`false`	When enabled, the app derives the bundle parent product's stock level from its components and writes it to Shopify (opt-in).
`Options Carrier Id`	`optionsCarrierId`	blank, or `parent-line`	blank	Only applies to a standard Options group (not Bundles, Build a Box, or Inventory sync). Blank routes answers onto the order's bundle grouping (no separate line; they won't reach packing slips or Order Printer). `parent-line` puts them on the product's own order line instead.
N/A	`id`	Optionfier option-set ID	N/A	JSON only. Exports include it; the XLSX format intentionally omits it (option sets match by handle).

Option fields

XLSX Column	JSON field	Accepted values	Default on create	Notes
`Set ID`	`id`	Optionfier option ID	N/A	Used for MERGE matching within an option set. Blank → create a fresh option.
`Set Handle`	`handle`	kebab-case slug, unique within the option set	required	Referenced by visibility conditions in other options.
`Set Command`	`command`	any string	N/A	Reserved for future use. Option-level commands are not read today; the option set's `Command` cascades to all children.
`Set Label On Cart`	`labelOnCart`	any text	N/A	Required for `NATIVE_BUNDLES` and `LINE_ITEM_PROPERTIES`. INVENTORY_ONLY options can omit it.
`Set Label On Product`	`labelOnProduct`	any text	the `labelOnCart`	Optional override for the storefront display.
`Set Enabled`	`enabled`	`true`, `false`	`true`	Disable an option without deleting it.
`Set Position`	`position`	number	`1.0`	Order within the parent option set.
`Set Required`	`required`	`true`, `false`	`false`	When `true`, customers must fill in this field to add to cart.
`Display On Frontend`	`displayOptionsOnFrontend`	`true`, `false`	`true`	When `false`, the option is hidden on the storefront.
`Treat As Line Item Property`	`treatAsLineItemProperty`	`true`, `false`	`false`	The Appears as setting: `true` is Text on order (the option shows as text on the parent line), `false` is Bundle items. Only honoured when `Inventory Engine` is `NATIVE_BUNDLES`. An `INVENTORY_ONLY` option set is always Text on order whatever this column says.
`Collect Color Value`	`collectColorValue`	`true`, `false`	`false`	For color-swatch sets: when `true`, the cart records the color's hex value next to the label (e.g. `Medium (#8D6944)`). Default records only the label.
`Dropdown Style`	`dropdownStyle`	`fancy`, `native`	`fancy`	Only applies to Selectable options rendered as a dropdown. `fancy` is Optionfier's own styled dropdown; `native` is the browser's plain `<select>`.
`Variant Image Size`	`variantImageSize`	`sm`, `md`, `lg`, or blank	blank (off)	Thumbnail size for a linked variant's image next to each choice. Blank turns the thumbnail off.
`Variant Image Position`	`variantImagePosition`	`leading`, `trailing`	`leading`	Which side of the choice label the variant thumbnail renders on.
`Show Component Pricing`	`showComponentPricing`	`true`, `false`	`false`	Shows the per-choice price next to each choice.
`Show Component Pricing Always`	`showComponentPricingAlways`	`true`, `false`	`false`	Also show prices that equal the parent variant's price.
`CSS Class Enabled`	`cssClassEnabled`	`true`, `false`	`false`	Master toggle for the custom CSS class.
`CSS Class`	`cssClass`	CSS class name	`""`	Custom class applied on the storefront.
`Placeholder Enabled`	`placeholderEnabled`	`true`, `false`	`false`	Master toggle for placeholder text.
`Placeholder Text`	`placeholderText`	any text	N/A	Grey helper text shown when no selection.
N/A	`lowStockNoticeEnabled`	`true`, `false`	`false`	JSON only, no XLSX column. Shows a "Only X left" notice on choices whose linked variant is running low.
N/A	`lowStockThreshold`	number or `null`	`null`	JSON only, no XLSX column. The stock level that triggers the low-stock notice.
N/A	`maxPerLine`	number or `null`	`null`	JSON only, no XLSX column. The most units of this product one cart line may hold, whether or not this option's choices are picked; checkout refuses lines over the cap. An out-of-range value is clamped to a usable cap rather than rejecting the whole file.
`Visibility Condition JSON`	`visibilityCondition`	JSON object or `null`	`null`	See Visibility Condition JSON below.
`Quantity By Source JSON`	`quantityBySource`	JSON object or `null`	`null`	Conditional-quantity rule: how many units of the linked variant this option consumes, driven by another option's answer. Same rule shape as `visibilityCondition`.

Excel round-trips every field above except the three marked JSON only. An Excel export/import of an option set with low-stock notices, a threshold, or a per-line cap silently drops them. Use JSON if you need those fields to survive the round-trip.

Common choice fields

Every choice carries the fields below. The type-specific fields live in Option Config JSON in Excel and at the top level of the option object in JSON (see Option Types and Per-Type Fields next).

XLSX Column	JSON field	Accepted values	Default on create	Notes
`Option ID`	`id`	Optionfier option ID	N/A	Used for MERGE matching within a set. Blank → create a fresh option.
`Option Type`	`type`	see types table below	required	Determines which per-type fields apply.
`Option Variant Product ID`	`variantProductId`	Shopify product GID	`""`	Connected component product.
`Option Variant Product Handle`	`variantProductHandle`	Shopify product handle	N/A	Denormalised reference kept in sync by the `products/update` webhook.
`Option Variant ID`	`matchingVariantId`	Shopify variant GID	`""`	Connected variant under the component product.
`Option Price Override`	`variantPriceOverride`	decimal string (e.g. `"12.99"`)	`null`	Custom price for an option shown as Bundle items. Ignored under `LINE_ITEM_PROPERTIES`.
`Option Quantity`	`quantity`	integer ≥ 1	`1`	How many units of the connected variant this option consumes.
`Option Inventory Management Enabled`	`inventoryManagementEnabled`	`true`, `false`	`false`	Per-option inventory tracking toggle.
`Option Config JSON`	(top-level keys on the option)	JSON blob	`{}`	XLSX-only; holds per-type fields without a dedicated column.

Option Types and Per-Type Fields

The Option Type value (or JSON type) is one of the following. Per-type fields below live in Option Config JSON in Excel and at the top level of the option object in JSON.

Option Type value	What it renders as
`SelectableOption`	Dropdown, radio, pill buttons, or product grid (picked via `displayAs`)
`CheckBoxOption`	Checkbox, pill toggle, or switch
`TextOption`	Text input (single- or multi-line)
`NumberOption`	Numeric input or slider
`DateOption`	Date picker
`TimeOption`	Time picker
`FileOption`	File upload
`ColorOption`	Predefined color swatch
`ImageSwatchOption`	Image swatch
`DynamicColorOption`	Customer-chosen hex color
`LinkedVariant`	Inventory link (for `INVENTORY_ONLY` inventory syncs; never shown on the storefront)
`StaticContentOption`	Structural content (heading, paragraph, divider, or spacer), collects no answer

XLSX Column / JSON key	Accepted values	Default	Notes
`Option Value` / `optionValue`	any text	required	The choice text shown to customers.
`Option Display As` / `displayAs`	`dropdown`, `radio`, `buttons`, `grid`	`dropdown`	Render style. `grid` is the Product grid: a wrapping grid of image tiles. Keep the same value across every option in a set.
`Option Selected By Default` / `selectedByDefault`	`true`, `false`	`false`	Pre-select this option on page load. At most one per set.

`CheckBoxOption`

XLSX Column / JSON key	Accepted values	Default	Notes
`Option Label` / `label`	any text	required	The checkbox label shown to customers.
`checkedByDefault`	`true`, `false`	required	Start checked when the page loads.
`displayAs`	`checkbox`, `buttons`, `switch`	`checkbox`	Standard checkbox, pill-button toggle, or an accessible switch.

`TextOption`

JSON key	Accepted values	Default	Notes
`placeholder`	any text	required	Grey helper text inside the field.
`multiLine`	`true`, `false`	required	Single-line input vs. textarea.
`validationType`	`none`, `email`, `telephone`, `url`	`none`	Pattern applied to the input.
`minLength`	integer ≥ 0 or `null`	`null`	Minimum character count.
`maxLength`	integer ≥ 1 or `null`	`null`	Maximum character count.

`NumberOption`

JSON key	Accepted values	Default	Notes
`placeholder`	any text	required	Grey helper text inside the field.
`minValue`	number or `null`	required	Minimum allowed value.
`maxValue`	number or `null`	required	Maximum allowed value.
`step`	positive number	`1`	Increment step.
`displayAs`	`input`, `slider`	`input`	Plain numeric field, or a range slider using the same min/max/step.

`DateOption`

JSON key	Accepted values	Default	Notes
`includeTime`	`true`, `false`	`false`	Combine with a time picker.
`minDate`	`YYYY-MM-DD` or `null`	required	Fixed lower bound.
`maxDate`	`YYYY-MM-DD` or `null`	required	Fixed upper bound.
`minDateRelative`	`{ anchor, offsetDays }` or `null`	`null`	Relative lower bound.
`maxDateRelative`	`{ anchor, offsetDays }` or `null`	`null`	Relative upper bound.
`specificDateRule`	`{ mode, dates }` or `null`	`null`	`mode` is `"block"` or `"allow"`; `dates` is an array of `YYYY-MM-DD`.
`dateRangeRule`	`{ mode, ranges }` or `null`	`null`	`ranges` is an array of `{ start, end }` (each `YYYY-MM-DD`).
`dayOfWeekRule`	`{ mode, days }` or `null`	`null`	`days` is an array of integers 0-6 (0 = Sunday).

Anchors for relative dates: today, startOfMonth, endOfMonth, startOfNextMonth, endOfNextMonth. offsetDays is an integer, positive for future, negative for past.

`TimeOption`

JSON key	Accepted values	Default	Notes
`minuteStep`	integer 1-60	`15`	Minute granularity.
`use24Hour`	`true`, `false`	`false`	24-hour vs. 12-hour display.
`minTime`	`HH:mm` or `null`	required	Fixed lower bound.
`maxTime`	`HH:mm` or `null`	required	Fixed upper bound.
`specificTimeRule`	`{ mode, times }` or `null`	`null`	`times` is an array of `HH:mm`.
`timeRangeRule`	`{ mode, ranges }` or `null`	`null`	`ranges` is an array of `{ start, end }` (each `HH:mm`).

`FileOption`

JSON key	Accepted values	Default	Notes
`acceptedTypes`	array of MIME types or extensions (e.g. `["image/*", ".pdf"]`)	required	File type restrictions.
`maxSizeMB`	positive number	required	Max per file. Subject to Shopify's 20 MB limit (1 GB for videos).

`ColorOption` (predefined swatches)

XLSX Column / JSON key	Accepted values	Default	Notes
`Option Color Name` / `colorName`	any text	required	Display name for the swatch.
`Option Color Value` / `colorValue`	hex string (e.g. `#FF5733`)	required	The swatch color.

`ImageSwatchOption`

XLSX Column / JSON key	Accepted values	Default	Notes
`Option Image URL` / `imageUrl`	URL	required	Source image for the swatch.
N/A / `optionName`	any text	required	Display name for the swatch. JSON only, no XLSX column.

`DynamicColorOption` (customer-chosen color)

No type-specific fields. Customers enter an arbitrary hex color at runtime.

`LinkedVariant` (inventory syncs)

JSON key	Accepted values	Default	Notes
`scope`	`GLOBAL`, `PER_VARIANT`	`GLOBAL`	`GLOBAL` = deduct for every trigger variant; `PER_VARIANT` = deduct only for the specific trigger variant below.
`triggerVariantId`	Shopify variant GID	`""`	Populated when `scope` is `PER_VARIANT`.
`triggerProductId`	Shopify product GID	`""`	Populated when `scope` is `PER_VARIANT`.

LinkedVariant choices also use the common matchingVariantId, variantProductId, variantProductHandle, and quantity fields; those identify the variant being deducted.

`StaticContentOption` (heading, paragraph, divider, spacer)

JSON key	Accepted values	Default	Notes
`kind`	`heading`, `paragraph`, `divider`, `spacer`	required	Which element this renders as.
`text`	any text	N/A	Heading or paragraph copy. Unused on divider/spacer.
`level`	`h2`, `h3`, `h4`	N/A	Heading only. The semantic level rendered on the storefront.
`size`	`sm`, `md`, `lg`	N/A	Divider/spacer only. The vertical spacing scale.

Visibility Condition JSON

The Visibility Condition JSON cell (XLSX) or visibilityCondition field (JSON) holds an object with this shape:

{
  "action": "show",
  "logic": "and",
  "rules": [
    {
      "sourceOptionSetId": "set_abcd1234efgh",
      "operator": "equals",
      "value": "Large"
    }
  ]
}

Key	Accepted values	Default	Notes
`action`	`show`, `hide`	`show`	Whether the rule shows or hides this option.
`logic`	`and`, `or`	`and`	Combiner across multiple rules.
`rules`	array of rule objects	required	See rule fields below.

Rule fields:

Key	Accepted values	Default	Notes
`sourceOptionSetId`	another option's `Set ID` in the same option set	required	The option whose value drives this rule.
`operator`	`equals`, `not_equals`	`equals`	Comparison.
`value`	string or `null`	required	The value to match against. `null` means "the source has any value" (useful with `not_equals` for "source is empty").

Fields Excluded from Export

A handful of DB fields are deliberately stripped during export and ignored on import. Including them in a hand-authored file has no effect:

variantPrice (choice): the live Shopify price, hydrated by the products/update webhook. Not merchant-editable.
optionSetId (choice): a foreign key regenerated by the importer at commit time.
parentInventorySnapshot (option set): live derived-inventory state, not merchant-editable.