Public API Guide

The AvisPlus Product Options Public API is a read-only REST API that allows merchants and external systems to retrieve option set data, app settings, and localization strings from outside the app.

Base URL: https://<your-app-host>/api/public/v1

Swagger UI: /api/public/docs

---

1. Authentication

All API requests require the following authorization header:

Authorization: Bearer <api-token>

• The API token is issued per shop. Each shop has one unique token.

• The shop must have an ACTIVE subscription and the app must not be uninstalled.

• If the shop does not meet these requirements, all requests will return 403.

Common error codes

Code	Description
401	Missing authorization header or invalid API key.
403	The shop does not have an active subscription.
404	The requested resource does not exist.
429	Rate limit exceeded: 60 requests per minute.
500	Server error.

Error responses always use the following format:

{
  "error": "<error description>"
}

---

2. Rate Limiting

• Limit: 60 requests per minute per shop.

• The rate limit uses a sliding window and is calculated by shop_id, which is identified from the API token.

• When the limit is exceeded, the API returns 429 with a message indicating when the request can be retried.

---

3. Endpoints

3a. List Option Sets

GET /api/public/v1/option-sets

Use this endpoint to retrieve a paginated list of option sets for a shop.

Query parameters

Fields marked with * are required.

Parameter	Type	Description
page	integer	Page number, 1-based. Default: 1.
limit	integer	Number of results per page. Minimum: 1, maximum: 100. Default: 20.
status	string	Filter option sets by status. Accepts "true" for active option sets or "false" for inactive option sets.
product_id	string	Filter option sets that apply to a specific Shopify product ID. This uses the same matching logic as the storefront: manual sets that contain the product, sets with type all, and automated sets whose conditions match the product’s tag, collection, type, vendor, title, or price.
name	string	Search option sets by name. Case-insensitive substring search. Example: color, wrap.
locale	string	BCP 47 language code, for example en, vi, fr, or de. When provided, the options array will be overlaid with translated values, and the response will include a translated flag.

Response 200

{
  "shop": "my-store.myshopify.com",
  "data": [
    {
      "_id": "option_set_id",
      "option_set_name": "Gift Wrap Options",
      "status": true,
      "type": "manual",
      "all_products": false,
      "products": ["1234567890"],
      "options": [],
      "sort": 0,
      "created_at": "2026-04-06T00:00:00.000Z",
      "updated_at": "2026-04-09T00:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 58,
    "pages": 3
  }
}

Sort order

The response is sorted by:

1. sort ascending

2. created_at descending

---

Field descriptions — data[] Option Set object

Field	Type	Description
_id	string	Unique option set ID. MongoDB ObjectId.
option_set_name	string	Display name of the option set.
status	boolean	Option set status. true = active, false = disabled.
type	string	Option set type. Accepted values: "manual" for specific products, "automated" for rule-based applying, or "all" for all products.
all_products	boolean	Whether the option set applies to all products in the shop.
products	array of strings	List of assigned Shopify product IDs. Only available when type = "manual".
options	array	Array of options in the option set, such as text, select, swatch, checkbox, and other option types. When locale is provided, this array is overlaid with translated values.
translated	boolean	Only appears when locale is provided. true = translations were applied, false = no translation was found and original values are returned.
sort	number	Sorting order. Smaller numbers appear first. Default: 0.
conditional_applying_product	object	Product auto-apply conditions. Used when type = "automated".
conditional_applying_customer	object	Customer-based applying conditions.
select_customer_type	string	Customer selection mode. Accepted values: "all", "manual", "automated", or "none".
customers	array	List of customer IDs. Only available when select_customer_type = "manual".
markets	object	Shopify Markets configuration.
exclude_products	object	Product exclusion configuration.
template_info	object	Template information. Only available when the option set was created from a template.
isClone	boolean	Indicates whether this option set was cloned from another option set.
cloneId	string	Source option set ID. Only available when isClone = true.
live_preview_bg	object	Background configuration for live preview.
save_count	number	Total number of times the option set has been saved.
option_set_tag	array of strings	Tags assigned to the option set.
import_from	string or null	Import source. Example: "easify". May be null or missing if the option set was created manually.
import_at	ISO date string	Import timestamp.
created_at	ISO date string	Creation timestamp.
updated_at	ISO date string	Last update timestamp.

---

Detailed structure — options[] Option object

Field	Type	Description
key	string	Unique option key. Nanoid, 30 characters.
type	string	Option type. See the Option Type Enum section below.
option_id	string	Unique option ID. Nanoid, 30 characters.
option_name	string	Internal option name. Used in the admin only and not displayed on the storefront.
label_product	string	Label displayed on the product page storefront.
label_cart	string	Label displayed in the cart or order.
input_name	string	Technical name describing the UI input type.
class_name	string	Custom CSS class.
required	boolean	Whether the customer is required to select or enter a value.
sort	number	Option sorting order inside the option set. Smaller numbers appear first.
default_value	string	Default value.
placeholder	string	Input placeholder.
min	string	Minimum value. Used by number and date.
max	string	Maximum value. Used by number and date.
min_length	string or number	Minimum character length. Used by text.
max_length	string	Maximum character length.
min_selections	string	Minimum number of selections. Used by multi-choice option types such as checkbox, button_multi, and swatch_multi.
max_selections	string	Maximum number of selections.
allow_multiple	string	Boolean-like string. Always "true" or "false", not a boolean.
allow_value	string	Input validation rule. Examples: "only_letters", "only_letters_number".
help_text	string	Help text shown to customers.
help_text_select	string	Help text display mode. Accepted values: "tooltip" or "none".
tooltip_display	string	Tooltip display mode. Accepted values: "hide", "show", or "value".
tooltip_text	string	Tooltip content.
new_help_text	string	New version of help text.
switch_label	string	Label for the switch option when type = "switch". Default: "Yes".
default_status	string or boolean	Default status for switch or group.
display_type	string	Display type. Accepted values: "accordion" for group or "hyperlink" for modal.
styles_heading	string	HTML heading tag. Accepted values: "h1" to "h6", or "p".
content_heading	string	Heading content when type = "heading".
border_styles	string	Border style. Accepted values: "solid", "none", or "dashed".
size_modal	string	Modal width in pixels. Default: "620".
title_on_product	string	Button text used to open the popup on the product page.
title_modal	string	Modal title.
image_popup_size	string	Image size inside the modal when type = "modal".
chart_title	string	Size chart title.
chart_header	string	Size chart header.
chart_icon_styles	string	Size chart icon style.
size_modal_size_chart	string	Size chart modal width in pixels.
font_selector	string	Font selector mode. Accepted values: "font_picker", "dropdown", or "googleFontPicker".
font_selected	array	Selected fonts.
custom_font_selected	array	Selected custom fonts.
option_show_price	string	Price display mode. Accepted values: "only_value", "only_label", "both", or "none".
add_price_quantity_type	string	Pricing mode by quantity. Accepted values: "each" for each product or "once" for one-time charge.
unit	string	Measurement unit. Used by dimension and slider. Default: "m".
step	number or object	Step value for number or slider, or multi-step configuration.
prefix	string or null	Display prefix.
suffix	string or null	Display suffix.
quantity_label	string	Label for advanced quantity input.
value_country	string	Country code. Default: "US".
is_color	boolean	Whether the swatch is a color swatch. true = color swatch, false = image swatch.
is_option_default_value	boolean	Whether the option has a default value.
option_default_value	string	Default value ID. Matches value_id in option_values.
show_option_value_qty	boolean	Whether to show a quantity input for each option value.
check_total_qty	boolean	Whether to validate total quantity.
is_onetime	boolean	Whether the charge is applied only once and not multiplied by product quantity.
addcharge_per_character	boolean	Whether to charge per entered character.
text_transform	string	Text transform setting. Accepted values: "uppercase", "lowercase", "capitalize", or "".
hide_price	boolean	Whether to hide the displayed price.
rich_text_value	string	Rich text content. Used by paragraph and html.
rich_text_value_modal	string	Rich text content for modal popup.
rich_text_value_size_chart	string	Rich text content for size chart.
rich_code_value_modal	string	Code editor content for modal when editor_type = "code_editor".
editor_type	string	Editor type for modal. Accepted values: "" for rich text or "code_editor".
group_id	number	Group ID. Only available when type = "option_group". Value is generated by Date.now().
group_parent	string	Parent group ID. Only available when the option belongs to a group.
step_parent	string	Parent step ID. Only available when the option belongs to a step.
button	object	Button configuration. Example: { "button_type": "combine", "step_required": true }.
dimension_price_total	string	Dimension-based pricing formula. Example: "x * {{price}}".
conditional_logic	object	Conditional show/hide logic. See the structure below.
slider	object	Slider configuration. See the structure below.
live_preview	object	Live preview configuration. See the structure below.
dimension_values	object	Dimension configuration. See the structure below.
inventory	object	Inventory configuration. See the structure below.
option_values	array	List of option values. See the OptionValue object section below.

---

conditional_logic structure

{
  "type": "show",
  "logic": "all",
  "condition_items": [
    {
      "field": "option_key",
      "type": "contains",
      "field_label": "Option Name",
      "value": "value_id"
    }
  ]
}

Field	Type	Description
type	string	Action when the condition matches. Accepted values: "show" or "hide".
logic	string	How conditions are combined. Accepted values: "all" for AND logic or "any" for OR logic.
condition_items[].field	string	Key of the option used for comparison.
condition_items[].type	string	Condition operator. Examples: "contains", "is".
condition_items[].field_label	string	Display label of the field.
condition_items[].value	string or null	Comparison value. Usually a value_id.

---

step structure

Used for multi-step options when type = "step".

{
  "items": [
    {
      "step_id": "string",
      "icon": "url",
      "name": "Step Name",
      "desc": "Description"
    }
  ],
  "layout": "step-dots"
}

Field	Type	Description
items	array	List of steps.
items[].step_id	string	Unique step ID.
items[].icon	string	Step icon URL.
items[].name	string	Step name.
items[].desc	string	Step description.
layout	string	Step layout style. Example: "step-dots".

---

slider structure

{
  "status": false,
  "rows": 1,
  "per_row": 2.5,
  "show_icon": true,
  "show_dot": false
}

Field	Type	Description
status	boolean	Whether the slider configuration is enabled.
rows	number	Number of rows.
per_row	number	Number of items per row.
show_icon	boolean	Whether to show icons.
show_dot	boolean	Whether to show dots.

---

live_preview structure

{
  "status": false,
  "default": {
    "value": "Your text",
    "opacity": 100,
    "color": "#000000",
    "font_type": "google",
    "font": "Roboto",
    "style": [],
    "size": "45",
    "width": "",
    "height": "160",
    "curved": "0",
    "shape": "rectangular",
    "image_scaling": "fit",
    "custom_shape": [],
    "align": "center",
    "image_preview": "",
    "type": "percent"
  },
  "position": {
    "x": "50",
    "y": "50",
    "r": "0"
  },
  "position_multiple": [
    {
      "x": "50",
      "y": "50",
      "r": "0",
      "width": "160",
      "height": "160",
      "url": "",
      "opacity": 100,
      "optionValueId": ""
    }
  ],
  "linked": {
    "font": "",
    "color_picker": "",
    "color_swatch": ""
  },
  "customer": {
    "position": false,
    "size": false,
    "type_size": "live_preview"
  }
}

Field	Type	Description
status	boolean	Whether live preview is enabled.
default	object	Default live preview configuration.
default.value	string	Default preview text.
default.opacity	number	Preview opacity.
default.color	string	Text or object color. Hex color.
default.font_type	string	Font source type. Example: "google".
default.font	string	Font name.
default.style	array	Font styles.
default.size	string	Preview size.
default.width	string	Preview width.
default.height	string	Preview height.
default.curved	string	Curved text setting.
default.shape	string	Preview shape. Example: "rectangular".
default.image_scaling	string	Image scaling mode. Example: "fit".
default.custom_shape	array	Custom shape configuration.
default.align	string	Alignment. Example: "center".
default.image_preview	string	Image preview URL or value.
default.type	string	Size or position unit type. Example: "percent".
position	object	Main preview position.
position.x	string	X position.
position.y	string	Y position.
position.r	string	Rotation.
position_multiple	array	Multiple preview positions.
linked	object	Linked option configuration.
linked.font	string	Linked font option key.
linked.color_picker	string	Linked color picker option key.
linked.color_swatch	string	Linked color swatch option key.
customer	object	Customer-adjustable live preview settings.
customer.position	boolean	Whether customers can adjust preview position.
customer.size	boolean	Whether customers can adjust preview size.
customer.type_size	string	Size adjustment type.

---

dimension_values structure

{
  "default": "66",
  "label": "Width",
  "X": {
    "label": "Width"
  },
  "Y": {
    "label": "Height"
  },
  "Z": {
    "label": "Depth"
  }
}

Field	Type	Description
default	string	Default dimension value.
label	string	Main dimension label.
X.label	string	Label for width.
Y.label	string	Label for height.
Z.label	string	Label for depth.

---

inventory structure

{
  "status": false,
  "items": [
    {
      "value_id": "string (for option_value) or undefined",
      "key": "string (for option input type) or undefined",
      "sku": "",
      "barCode": "",
      "available": "0",
      "onHand": "0",
      "committed": "0",
      "unavailable": "0",
      "tracked": false,
      "continueSelling": false,
      "option_name": "",
      "option_value": ""
    }
  ]
}

Field	Type	Description
status	boolean	Whether inventory tracking is enabled for this option.
items	array	List of inventory items. Each item corresponds to an option value or an input-type option.
items[].value_id	string or undefined	ID of the option value. May exist when the item belongs to an option_value.
items[].key	string or undefined	Option key. May exist when the item belongs to an input-type option such as text or number.
items[].sku	string	SKU.
items[].barCode	string	Barcode.
items[].available	string or number	Available inventory quantity.
items[].onHand	string or number	Actual on-hand inventory quantity.
items[].committed	string or number	Committed quantity, usually reserved by existing orders.
items[].unavailable	string or number	Unavailable inventory quantity.
items[].tracked	boolean	Whether inventory is tracked.
items[].continueSelling	boolean	Whether selling continues when out of stock.
items[].option_name	string	Option name.
items[].option_value	string	Option value name.

---

Detailed structure — option_values[] OptionValue object

Field	Type	Description
value_id	string	Unique value ID. Nanoid, 30 characters.
value	string	Label displayed on the storefront. Examples: "Red", "Size M", "Custom text".
type	string	Pricing type. See the Value Type Enum section below.
isValueActive	string	Boolean-like string. Always "TRUE" for active or "FALSE" for disabled, not a boolean.
price	number	Fixed additional price. Decimal value. Example: 5.99.
percentageCharge	number	Percentage-based charge based on the original product price. Example: 10 means 10%.
option_show_price	string	Price display mode. Accepted values: "only_value", "only_label", "both", or "none".
productId	string	Linked Shopify product ID. Used for charge or bundle logic.
productVariationId	string	Linked Shopify variant ID.
productName	string	Linked product name.
variantId	string	Shopify variant ID.
variantName	string	Variant name.
variantBundleName	string	Variant name in bundle logic.
productBundleName	string	Product name in bundle logic.
handle	string	Shopify product handle.
is_product_bundle	boolean	Whether the value is part of bundle logic.
isAdd	boolean	Add charge flag.
variant_image	string	Variant image URL.
inventory_quantity	number	Cached inventory quantity from Shopify.
des_value	string	HTML description or tooltip content for the value.
swatch	object	Swatch display configuration. See the structure below.

---

swatch structure

{
  "color": "#FF0000",
  "file_image": {},
  "file_image_url": "https://...",
  "is_color": true,
  "colors_number": "one"
}

Field	Type	Description
color	string	Hex color. Example: "#FF0000".
file_image	object	Uploaded file data used by the frontend.
file_image_url	string	Swatch image URL.
is_color	boolean	Whether the swatch displays a color or an image. true = color swatch, false = image swatch.
colors_number	string	Number of colors displayed. Accepted values: "one" or "two".

---

Option Type Enum

Valid values for options[].type.

Type	Description
text	Single-line text input.
textarea	Multi-line text input.
number	Number input.
email	Email input.
phone	Phone number input.
date	Date or datetime picker.
file	File upload.
color	Color picker.
font	Font selector.
switch	On/off toggle.
slider	Numeric slider.
quantity	Quantity input.
dimension	Dimension input, such as W × H × D.
hidden_field	Hidden field.
radio	Radio buttons.
checkbox	Checkboxes.
button_single	Button, single selection.
button_multi	Button, multiple selection.
select	Drop-down menu.
combo_box	Combo box.
combo_select	Combo dropdown.
combo_color	Combo color.
combo_image	Combo image.
swatch	Swatches, legacy or generic.
swatch_single_color	Color swatch, single selection.
swatch_single_image	Image swatch, single selection.
swatch_multi_color	Color swatch, multiple selection.
swatch_multi_image	Image swatch, multiple selection.
swatch_select_color	Color dropdown.
swatch_select_image	Image dropdown.
paragraph	Display text.
heading	Display heading.
html	Custom HTML.
divider	Divider line.
space	Spacer.
modal	Popup modal.
size_chart	Size chart.
step	Multi-step wizard.
option_group	Option group.

---

Value Type Enum

Valid values for option_values[].type.

Type	Description
adjustprice	Fixed additional price.
percentagecharge	Percentage-based charge based on the original product price.
chargeorbundle	Charge or bundle linked to a product or variant.
useexistingvariant	Use an existing Shopify variant.
createcharge	Create a new charge as a separate line item.

---

Important notes

1. Boolean-like values stored as strings

   Some fields look like booleans but are actually returned as strings.

   • isValueActive is always "TRUE" or "FALSE", not a boolean.

   • allow_multiple is always "true" or "false", not a boolean.

   • app_status is always "true" or "false", not a boolean.

   Client applications should parse these fields as strings unless explicitly converted.

2. IDs

   key, option_id, and value_id are 30-character nanoid strings or UUID v4 values.

3. Price

   Price values are always numbers and may contain decimals.

4. Group ID

   group_id only exists when type = "option_group". Its value is a timestamp generated by Date.now().

5. Group and step parents

   group_parent and step_parent only exist when an option is a child of a group or a step.

6. Swatch types

   • is_color = true means the swatch is a color swatch.

   • is_color = false means the swatch is an image swatch.

7. Inventory

   Real inventory data is hydrated from a separate collection and is not stored directly inside option_sets.

---

Field descriptions — pagination

Field	Type	Description
page	integer	Current page.
limit	integer	Number of results per page.
total	integer	Total number of option sets matching the filter.
pages	integer	Total number of pages. Calculated by Math.ceil(total / limit).

---

3b. Get Option Set by ID

GET /api/public/v1/option-sets/:id

Use this endpoint to retrieve a single option set by ID.

Input

Fields marked with * are required.

Parameter	Type	Description
id *	string	Path parameter. MongoDB ObjectId of the option set.
locale	string	Query parameter. BCP 47 language code, for example en, vi, fr, or de. When provided, the options array is overlaid with translated values, and the response includes a translated flag.

Response 200

{
  "shop": "my-store.myshopify.com",
  "data": {
    "_id": "option_set_id",
    "option_set_name": "Gift Wrap Options",
    "status": true,
    "type": "manual",
    "options": []
  }
}

The data object uses the same structure as each item in data[] from the List Option Sets API.

Response 404

Returned when the id does not exist or the option set has been soft-deleted.

{
  "error": "Option set not found"
}

---

3c. Get Settings

GET /api/public/v1/settings

Use this endpoint to retrieve app settings for the shop.

Input

This endpoint does not require query parameters.

The shop is automatically identified from the API token.

Response 200

{
  "shop": "my-store.myshopify.com",
  "data": {
    "_id": "...",
    "app_status": "true",
    "use_css_version": "v2",
    "shopify_option": {},
    "show_add_charge_feat": true,
    "show_conditional_logic_feat": true
  }
}

---

Field descriptions — Settings data

Field	Type	Description
_id	string	Settings document ID.
app_status	string	Boolean-like string. Always "true" for enabled or "false" for disabled, not a boolean.
use_css_version	string	CSS rendering version. Accepted values: "v1" or "v2".
shopify_option	object	Shopify option display configuration. Controls whether native Shopify options are shown or hidden on the storefront.
show_add_charge_feat	boolean	Whether the add charge or extra pricing feature is enabled.
show_conditional_logic_feat	boolean	Whether the conditional logic feature is enabled.
widget	object	AvisPlus widget configuration. Includes fields such as position, enabled, and other widget settings.
s_option_img	object	Swatch image display configuration.
s_option_backg_size	string	CSS background-size value for image swatches.
s_option_show_tooltip	boolean	Whether to show tooltip on swatch hover.
add_to_cart_style	object	Add-to-cart button style configuration.
cart_page	object	Option display configuration for the cart page.
product_page	object	Option display configuration for the product page. validate_settings ("inline" or "alert") and validate_effect may be auto-computed from the shop’s app installation history if not explicitly set.
custom_css	string	Custom CSS injected into the storefront.
app_embed	boolean	Whether the app embed extension is active on the current theme.
app_embed_theme_id	string	ID of the theme where app embed is enabled.
app_embed_theme_name	string	Name of the theme where app embed is enabled.
theme_version	string	Theme version string.
hide_hover_img_swatches	boolean	Whether to hide hover images for swatches.
show_watermark_on_product_page	boolean	Whether to show the AvisPlus watermark on the product page.
listFonts	array of objects	Custom fonts uploaded by the merchant. Each item may include name, family, type, css, and fontURL.

---

3d. Get Localizations

GET /api/public/v1/localizations

Use this endpoint to retrieve localization strings for a specific locale.

Query parameters

Fields marked with * are required.

Parameter	Type	Description
locale *	string	BCP 47 language code. Examples: en, vi, fr, de. If this parameter is missing, the API returns 400.

Response 200

{
  "shop": "my-store.myshopify.com",
  "locale": "en",
  "has_overrides": true,
  "data": {
    "text_price_add": "+{price_add}",
    "text_alert_required_min_characters": "Minimum {min} characters required",
    "dynamic_checkout_notification": "Please select all required options",
    "text_total_price": "Total: {total}"
  }
}

---

Field descriptions — Localizations

Field	Type	Description
shop	string	Shop domain identified from the authenticated API token.
locale	string	Locale code passed by the client.
has_overrides	boolean	Whether there is a separate setting_locales document for this locale. true = locale-specific overrides exist, false = response only uses base strings from display_settings.
data	object	Object in key → translated string format. Base values come from display_settings; overrides from setting_locales[locale].data are merged on top. Empty values such as null or "" in overrides fall back to the base value.

---

Common translation keys in data

Key	Type	Description
text_price_add	string	Format for displaying additional price. Placeholder: {price_add}.
customize_alert_required_min_characters	string	Alert shown when the input is below the minimum character length. Placeholder: {min}.
dynamic_checkout_notification	string	Message shown near checkout when required options have not been selected.
add_to_cart	string	Text for the “Add to cart” button.
added_to_cart	string	Message shown after a product is added to the cart.
sold_out	string	Text displayed when the product is sold out.

Localization fallback behavior

If no setting_locales document is found for the requested locale, the API still returns 200.

In that case:

• has_overrides will be false.

• data will be returned from the base display_settings.

• The API does not return 404 for missing locale overrides.

---

4. Versioning and changelog

Versioning

The current base path is:

/api/public/v1

Breaking changes will be released under a new version path, for example:

/api/public/v2

Adding new fields is not considered a breaking change. Client applications should ignore unknown fields to remain compatible with future updates.

Changelog

Date	Change
2026-04-09	Added the translated field to option-sets responses when the locale query parameter is provided.
2026-04-06	Released Public API v1 with option sets list/detail, settings, and localizations endpoints.