Skip to content

Advanced Product OptionsGetting started

Case 1: Import your first option set

Use this flow when you want to create your first option set from scratch.

APO setup guide with the Import button next to Create new options

Option sets page with the Import button in the top bar

Download the Sample CSV, edit it, then import it back. The sample already includes the correct structure and all supported column headers.

Import option sets by CSV modal with the Download sample CSV link highlighted

Leave these columns empty or delete to create new data: Set ID, Option ID, Value ID. If you fill any of them, the import will treat the row as an update attempt.

Sample CSV with empty Set ID, Option ID and Value ID columns highlighted

Each row can describe only one level: a set, an option, or a value. Because of this, some cells must always stay empty. If a row contains data in cells from multiple levels, the import will fail. Row order defines hierarchy: values go under options, options go under sets.

  • If you are creating a set row: option and value columns must be empty.
  • If you are creating an option row: set and value columns must be empty.
  • If you are creating a value row: set and option columns must be empty.

CSV rows where set, option and value data each sit on separate rows

At minimum, your CSV must contain the required naming fields for every level and every option type.

  1. For the option set, fill Set Title.
  2. For every option, including content options (Heading, Paragraph, Image, etc.) and input options, fill Option Title and Option Type.
  3. For every value, including values used by content and structural options, fill Value Title.

CSV with required Set Title, Option Title, Option Type and Value Title cells highlighted

ColumnWhat to enterAllowed / example values
Set IDLeave empty when creating a new option set.
Keep the existing value when updating a set.
Auto-generated ID from export, for example:
401
Set TitleThe name of the option set. This is required.

Must not be empty.
Any text, for example:
Camera options
Winter customization
Extras for T-shirt
Set StatusTurn the option set on or off1 = active,
0 = inactive (Default)
Assign TypeHow to assign the set to productsproduct_handles or conditions
Assigned Dataproduct_handles





or conditions
product_handles: 5-panel-hat

When assigning a set to multiple products by handle, list the handles in one cell separated by a vertical bar:

product_handles: camera\
Option IDLeave empty when creating a new option.
Keep the existing value when updating an option.
Existed Option ID from export, for example:
o_812
Option TitleThe option name shown to customers. Required for all option types, including content options.

Must not be empty.
Any text, for example:
Color
Size
Extras
Option Help TextOptional helper text shown under the option on the storefront.Any text, for example:
Choose one option
Leave empty if not needed.
Option TypeThe option input type. Required.

Enter the option type exactly as shown in the UI.

If the option type does not match exactly, the import will fail.
Swatch
Swatch in pill
Swatch card
Swatch in dropdown
Wide image card
Button
Tile
Dropdown
Radio button
Multi-select swatch
Multi-select swatch in pill
Multi-select swatch card
Multi-select wide image card
Multi-select button
Multi-select tile
Checkbox
Text box
Multi-line text box
Number field
Step counter
Range slider
Date picker
File upload
Heading
Paragraph
Image
Divider
Spacer
Modal
HTML-block
Option Is RequiredIs the option mandatory1 = yes,
0 = no
Option SortThe order of the option inside the option set.Positive number, for example:
1, 2, 10

Lower number = higher position.
Leave empty (or 0) to keep the current order.
CSS ClassOptional custom CSS class for the option.[“a”,“b”]
Leave empty if not used.
Value IDLeave empty when creating a new value.
Keep the existing value when updating a value.
Existed Value ID from export, for example:
v_3104
Value TitleThe value name shown to customers. Required for all values, including input and content options.Any text, for example:
Red
Large
Default value
Value Help TextOptional helper text shown next to or under the value on the storefront.Any text, for example:
Most popular choice
Leave empty if not needed.
Value BadgeA badge label displayed next to the value.Example (preset text badge):
{“color”:“#D72C0D”,“key”:“hot”,“text”:“HOT”,“type”:“text”,“uid”:null}
Paste the object exactly as shown


Custom badges require a valid uid. At the moment, new uid values cannot be generated during CSV import. This means:
1. You can reuse an existing custom badge by keeping its uid
2. You cannot create a brand-new custom badge via CSV import

{“color”:“#FFB800”,“key”:“custom_text”,“text”:“Custom Badge”,“type”:“text”,“uid”:“dox2agxr6rzc”}

If you need to create new custom badges via import, please contact our support team.
Value Images / ColorsImage or color for the valueSingle color swatch:
color:#44215E, is_visible:1

Double color swatch:
first_color:#EAE4DB, second_color:#2A2828, is_visible:1

Image URLs must be direct, publicly accessible links hosted on a server. During import, images are copied and stored on the APO server.

Single image:
url:https://example.com/image.png, is_visible:1

Multiple images:
url:https://example.com/image1.png, is_visible:1 \
Value StatusControls how the value behaves on the storefront.active
The value is visible and can be selected.

unavailable (only for select-type options)
The value is visible but cannot be selected.

archived (only for select-type options)
The value is hidden and not displayed on the product page. Not applicable to input or content options.
Value Is DefaultMarks the value as selected by default.Allowed / example values
1 = default value
0 = not default

Important: Only one value per option can be set as default (except multiple selection option types).
Value SortControls the order of values inside the option.Positive number, for example:
1, 2, 10

Lower number = higher position.
Leave empty (or 0) to keep the current order.
Pricing TypeHow the price is calculatedfixed or percent
Price ValuePrice amount10, -5, 7.5
Compare-at PriceCompare-at price15, 0
Pricing Is One-TimeOne-time price1 = yes, 0 = no
Addon Link TypeHow the add-on product is linked to the option value.handle — link by product handle

variant_id — link by specific product variant ID
Addon LinkThe identifier of the add-on product. Must match the selected Add-on Link Type.When Add-on Link Type = handle:
product_1

When Add-on Link Type = variant_id:
45318880297175
Use Addon ImageWhether to use the add-on product image as the option value image.1 = yes, 0 = no
Hover Addon ImageWhether to enlarge the add-on product image on hover.

Works only if Use Add-on Image = 1.
1 = yes, 0 = no
Inventory Is EnabledEnable value quantity limit1 = enabled,
0 = disabled
Value SKUSKU for the valueSKU-RED-01
Is Physical ProductIs the value physical1 = physical,
0 = digital
Value WeightWeight amount0.5, 250
Value Weight UnitWeight unitg, kg, lb, oz

Click Import in the Option Sets list to upload your edited CSV file.

APO setup guide with the Import button highlighted

Option sets page with the Import button next to Export and Create new options

This opens the CSV import modal. Select your edited CSV file and click Import.

Import option sets by CSV modal with a CSV file attached and the Import button

After starting the import, it runs asynchronously. You can continue working in the admin.

Go to Settings → Import & Export to see the import progress and result.

Import and export statuses are not updated automatically.

Click Refresh to see the latest status.

Settings Import & Export tab with the Refresh button and a Finished import status

Possible outcomes:

  • Finished - Import completed successfully and changes are applied.
  • Failed - Import was not applied. An Issues report is available. Click Issues report to download the file, fix the errors, and re-import. If the import fails: nothing is partially saved, existing option sets remain unchanged. Safely fix the CSV and try again, or restore a backup if needed.

Nothing breaks. If something is wrong, the import will not be partially applied.

Import & Export list with an import marked Issues and its Issues report link

You will receive an import report explaining what needs to be fixed. After fixing the file, you can upload it again.

Issues report CSV flagging rows where Option Title or Value Title is required

No. You only need to fill the required title fields and the columns that matter for your setup. All other columns can stay empty.

Which columns are required for a basic import?

Section titled “Which columns are required for a basic import?”

At minimum 4:

  • Set Title for each option set
  • Option Title and Option Type for every option (including content and input options)
  • Value Title for every value

Titles can contain any text. The exact wording does not matter. Cells must not be empty.

Minimal CSV with Set Title, Option Title, Option Type and Value Title columns filled

Which columns must stay empty when creating a new set?

Section titled “Which columns must stay empty when creating a new set?”

When importing your first option set, leave these columns empty:

  • Set ID
  • Option ID
  • Value ID

Empty IDs always mean “create new”.

Can I assign the option set to products during import?

Section titled “Can I assign the option set to products during import?”

Yes, but it is optional.

If you don’t want to assign the set yet, leave Assign Type and Assigned Data empty.

You can always assign products later from the admin UI.

No. Pricing is optional.

If a value should not affect the product price, leave all pricing columns empty.

Pricing is defined per value, not per option.

Yes. Even content options (Heading, Paragraph, Image, Divider, etc.) require:

  • Option Title
  • at least one Value row with a Value Title

The value title can be any text and is used internally.