> For the complete documentation index, see [llms.txt](https://options-docs-v2.avisplus.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://options-docs-v2.avisplus.io/integration/api-and-webview-reference.md).

# API & Webview reference

## 1. API Host, Base URL, and Swagger

### API Host

```
https://public-api.avisplus.io
```

### Base URL

```
https://public-api.avisplus.io/api/public/v1
```

### Swagger UI

```
https://public-api.avisplus.io/swagger/
```

Use Swagger UI to check the latest request/response schema and test API endpoints.

### GitBook expandable blocks

Long examples and sample responses are placed inside expandable sections to keep the page easier to scan.

### Version path

The current API version 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.

***

## 2. Authentication

All API requests require the following authorization header:

```http
Authorization: Bearer <api-token>
```

### API token rules

* The API token is issued per shop.
* Each shop has one unique API token.
* The shop must have an active app subscription.
* The app must not be uninstalled from the shop.
* If the shop does not meet these requirements, requests will return `403`.

### Token handling

In Avis option app, navigate to **API Gateway** > Scroll down to **Create your API Token** to generate your unique API token

<figure><img src="/files/PC85TPoleFJay3IATPbu" alt=""><figcaption></figcaption></figure>

Keep the API token secure. Do not publish it in public repositories, screenshots, client-side storefront code, or public documents.

***

## 3. Error Format

Error responses use the following format:

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

### Common error codes

<table><thead><tr><th width="89">Code</th><th>Description</th></tr></thead><tbody><tr><td><code>400</code></td><td>Bad request. Required query parameter is missing or invalid.</td></tr><tr><td><code>401</code></td><td>Missing authorization header or invalid API token.</td></tr><tr><td><code>403</code></td><td>The shop does not have an active subscription, or the app is uninstalled.</td></tr><tr><td><code>404</code></td><td>The requested resource does not exist.</td></tr><tr><td><code>429</code></td><td>Rate limit exceeded.</td></tr><tr><td><code>500</code></td><td>Server error.</td></tr></tbody></table>

***

## 4. Rate Limiting

| Rule              | Value                                    |
| ----------------- | ---------------------------------------- |
| Limit             | 60 requests per minute per shop          |
| Calculation       | Sliding window                           |
| Identifier        | `shop_id`, identified from the API token |
| Exceeded response | `429` with a retry message               |

***

## 5. Endpoints Overview

<table><thead><tr><th width="138">Method</th><th width="187">Endpoint</th><th>Purpose</th></tr></thead><tbody><tr><td><code>GET</code></td><td><code>/api/public/v1/option-sets</code></td><td>Retrieve a paginated list of option sets.</td></tr><tr><td><code>GET</code></td><td><code>/api/public/v1/option-sets/:id</code></td><td>Retrieve a single option set by ID.</td></tr><tr><td><code>GET</code></td><td><code>/api/public/v1/settings</code></td><td>Retrieve app settings for the authenticated shop.</td></tr><tr><td><code>GET</code></td><td><code>/api/public/v1/localizations</code></td><td>Retrieve localization strings for a specific locale.</td></tr></tbody></table>

***

## 6. List Option Sets

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

```http
GET /api/public/v1/option-sets
```

### Query parameters

<table><thead><tr><th width="144">Parameter</th><th width="90" align="right">Type</th><th width="88" align="center">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>page</code></td><td align="right">integer</td><td align="center">No</td><td>Page number, 1-based. Default: <code>1</code>.</td></tr><tr><td><code>limit</code></td><td align="right">integer</td><td align="center">No</td><td>Number of results per page. Minimum: <code>1</code>, maximum: <code>100</code>. Default: <code>20</code>.</td></tr><tr><td><code>status</code></td><td align="right">string</td><td align="center">No</td><td>Filter by option set status. Accepts <code>"true"</code> for active option sets or <code>"false"</code> for inactive option sets.</td></tr><tr><td><code>product_id</code></td><td align="right">string</td><td align="center">No</td><td>Filter option sets that apply to a specific Shopify product ID. The API uses the same matching logic as the storefront: manual sets assigned to the product, all-product sets, and automated sets whose conditions match the product.</td></tr><tr><td><code>name</code></td><td align="right">string</td><td align="center">No</td><td>Case-insensitive substring search by option set name. Example: <code>color</code>, <code>wrap</code>.</td></tr><tr><td><code>locale</code></td><td align="right">string</td><td align="center">No</td><td>BCP 47 language code, for example <code>en</code>, <code>vi</code>, <code>fr</code>, or <code>de</code>. When provided, option labels and values are overlaid with translated values when available.</td></tr></tbody></table>

### Sort order

The response is sorted by:

1. `sort` ascending
2. `created_at` descending

<details>

<summary>Example request</summary>

```bash
curl -X GET "https://public-api.avisplus.io/api/public/v1/option-sets?page=1&limit=20&status=true&product_id=1234567890&locale=en" \
  -H "Authorization: Bearer <api-token>"
```

</details>

<details>

<summary>Response 200</summary>

```json
{
  "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
  }
}
```

</details>

### `data[]` Option Set object

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

### `pagination` object

| 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)`. |

***

## 7. Get Option Set by ID

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

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

### Input

<table><thead><tr><th width="107">Parameter</th><th width="105" align="right">Type</th><th width="108" align="center">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>id</code></td><td align="right">string</td><td align="center">Yes</td><td>Path parameter. MongoDB ObjectId of the option set.</td></tr><tr><td><code>locale</code></td><td align="right">string</td><td align="center">No</td><td>Query parameter. BCP 47 language code. When provided, option labels and values are overlaid with translated values when available.</td></tr></tbody></table>

<details>

<summary>Example request</summary>

```bash
curl -X GET "https://public-api.avisplus.io/api/public/v1/option-sets/option_set_id?locale=en" \
  -H "Authorization: Bearer <api-token>"
```

</details>

<details>

<summary>Response 200</summary>

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

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

</details>

<details>

<summary>Response 404</summary>

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

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

</details>

***

## 8. Get Settings

Use this endpoint to retrieve app settings for the authenticated shop.

```http
GET /api/public/v1/settings
```

The shop is automatically identified from the API token. This endpoint does not require query parameters.

<details>

<summary>Example request</summary>

```bash
curl -X GET "https://public-api.avisplus.io/api/public/v1/settings" \
  -H "Authorization: Bearer <api-token>"
```

</details>

<details>

<summary>Response 200</summary>

```json
{
  "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
  }
}
```

</details>

### Settings data

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

***

## 9. Get Localizations

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

```http
GET /api/public/v1/localizations
```

### Query parameters

<table><thead><tr><th width="126.9998779296875">Parameter</th><th width="98" align="right">Type</th><th width="107" align="center">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>locale</code></td><td align="right">string</td><td align="center">Yes</td><td>BCP 47 language code. Examples: <code>en</code>, <code>vi</code>, <code>fr</code>, <code>de</code>. If this parameter is missing, the API returns <code>400</code>.</td></tr></tbody></table>

<details>

<summary>Example request</summary>

```bash
curl -X GET "https://public-api.avisplus.io/api/public/v1/localizations?locale=en" \
  -H "Authorization: Bearer <api-token>"
```

</details>

<details>

<summary>Response 200</summary>

```json
{
  "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}"
  }
}
```

</details>

### Localization fields

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

### Localization fallback behavior

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

In that case:

* `has_overrides` is `false`.
* `data` is returned from the base `display_settings`.
* The API does not return `404` for missing locale overrides.

### Common translation keys in `data`

<table><thead><tr><th>Key</th><th width="104">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>text_price_add</code></td><td>string</td><td>Format for displaying additional price. Placeholder: <code>{price_add}</code>.</td></tr><tr><td><code>customize_alert_required_min_characters</code></td><td>string</td><td>Alert shown when the input is below the minimum character length. Placeholder: <code>{min}</code>.</td></tr><tr><td><code>dynamic_checkout_notification</code></td><td>string</td><td>Message shown near checkout when required options have not been selected.</td></tr><tr><td><code>add_to_cart</code></td><td>string</td><td>Text for the “Add to cart” button.</td></tr><tr><td><code>added_to_cart</code></td><td>string</td><td>Message shown after a product is added to the cart.</td></tr><tr><td><code>sold_out</code></td><td>string</td><td>Text displayed when the product is sold out.</td></tr></tbody></table>

***

## 10. Option Object

`options[]` contains the option fields inside an option set.

### Important identifier mapping

This is the most important part when consuming option data externally:

| Field                      | Meaning                                                  | Recommended usage                                                   |
| -------------------------- | -------------------------------------------------------- | ------------------------------------------------------------------- |
| `key`                      | Stable unique option key. Usually a 30-character nanoid. | Use this as the main option identifier in external logic.           |
| `option_id`                | Unique option ID.                                        | Internal option ID. Do not confuse this with `key`.                 |
| `option_name`              | Internal option name used in admin.                      | For admin/internal reference only. Not the storefront label.        |
| `label_product`            | Label displayed on the product page.                     | Use this as the customer-facing label on product page UI.           |
| `label_cart`               | Label displayed in cart or order.                        | Use this as the customer-facing label in cart/order UI.             |
| `option_values[].value_id` | Unique ID of a selectable value.                         | Use this as the selected value identifier for choice-based options. |

For conditional logic, `condition_items[].field` must use the controlling option’s `options[].key`. It should not use `option_id`, `option_name`, or the display label.

### Key fields

<table><thead><tr><th width="233">Field</th><th width="168">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>key</code></td><td>string</td><td>Unique option key. Usually a 30-character nanoid.</td></tr><tr><td><code>type</code></td><td>string</td><td>Option type. See Option Type Enum.</td></tr><tr><td><code>option_id</code></td><td>string</td><td>Unique option ID. Usually a 30-character nanoid.</td></tr><tr><td><code>option_name</code></td><td>string</td><td>Internal option name. Used in the admin only and not displayed on the storefront.</td></tr><tr><td><code>label_product</code></td><td>string</td><td>Label displayed on the product page storefront.</td></tr><tr><td><code>label_cart</code></td><td>string</td><td>Label displayed in the cart or order.</td></tr><tr><td><code>input_name</code></td><td>string</td><td>Technical name describing the UI input type.</td></tr><tr><td><code>class_name</code></td><td>string</td><td>Custom CSS class.</td></tr><tr><td><code>required</code></td><td>boolean</td><td>Whether the customer is required to select or enter a value.</td></tr><tr><td><code>sort</code></td><td>number</td><td>Option sorting order inside the option set. Smaller numbers appear first.</td></tr><tr><td><code>default_value</code></td><td>string</td><td>Default value.</td></tr><tr><td><code>placeholder</code></td><td>string</td><td>Input placeholder.</td></tr><tr><td><code>min</code></td><td>string</td><td>Minimum value. Used by <code>number</code> and <code>date</code>.</td></tr><tr><td><code>max</code></td><td>string</td><td>Maximum value. Used by <code>number</code> and <code>date</code>.</td></tr><tr><td><code>min_length</code></td><td>string or number</td><td>Minimum character length. Used by <code>text</code>.</td></tr><tr><td><code>max_length</code></td><td>string</td><td>Maximum character length.</td></tr><tr><td><code>min_selections</code></td><td>string</td><td>Minimum number of selections. Used by multi-choice option types such as <code>checkbox</code>, <code>button_multi</code>, and <code>swatch_multi</code>.</td></tr><tr><td><code>max_selections</code></td><td>string</td><td>Maximum number of selections.</td></tr><tr><td><code>allow_multiple</code></td><td>string</td><td>Boolean-like string. Always <code>"true"</code> or <code>"false"</code>, not a boolean.</td></tr><tr><td><code>allow_value</code></td><td>string</td><td>Input validation rule. Examples: <code>only_letters</code>, <code>only_letters_number</code>.</td></tr><tr><td><code>help_text</code></td><td>string</td><td>Help text shown to customers.</td></tr><tr><td><code>help_text_select</code></td><td>string</td><td>Help text display mode. Accepted values: <code>tooltip</code> or <code>none</code>.</td></tr><tr><td><code>tooltip_display</code></td><td>string</td><td>Tooltip display mode. Accepted values: <code>hide</code>, <code>show</code>, or <code>value</code>.</td></tr><tr><td><code>tooltip_text</code></td><td>string</td><td>Tooltip content.</td></tr><tr><td><code>switch_label</code></td><td>string</td><td>Label for the switch option when <code>type = "switch"</code>. Default: <code>Yes</code>.</td></tr><tr><td><code>default_status</code></td><td>string or boolean</td><td>Default status for switch or group.</td></tr><tr><td><code>display_type</code></td><td>string</td><td>Display type. Accepted values: <code>accordion</code> for group or <code>hyperlink</code> for modal.</td></tr><tr><td><code>styles_heading</code></td><td>string</td><td>HTML heading tag. Accepted values: <code>h1</code> to <code>h6</code>, or <code>p</code>.</td></tr><tr><td><code>content_heading</code></td><td>string</td><td>Heading content when <code>type = "heading"</code>.</td></tr><tr><td><code>option_show_price</code></td><td>string</td><td>Price display mode. Accepted values: <code>only_value</code>, <code>only_label</code>, <code>both</code>, or <code>none</code>.</td></tr><tr><td><code>add_price_quantity_type</code></td><td>string</td><td>Pricing mode by quantity. Accepted values: <code>each</code> or <code>once</code>.</td></tr><tr><td><code>unit</code></td><td>string</td><td>Measurement unit. Used by <code>dimension</code> and <code>slider</code>. Default: <code>m</code>.</td></tr><tr><td><code>step</code></td><td>number or object</td><td>Step value for number or slider, or multi-step configuration.</td></tr><tr><td><code>prefix</code></td><td>string or null</td><td>Display prefix.</td></tr><tr><td><code>suffix</code></td><td>string or null</td><td>Display suffix.</td></tr><tr><td><code>quantity_label</code></td><td>string</td><td>Label for advanced quantity input.</td></tr><tr><td><code>value_country</code></td><td>string</td><td>Country code. Default: <code>US</code>.</td></tr><tr><td><code>is_color</code></td><td>boolean</td><td>Whether the swatch is a color swatch. <code>true</code> = color swatch, <code>false</code> = image swatch.</td></tr><tr><td><code>is_option_default_value</code></td><td>boolean</td><td>Whether the option has a default value.</td></tr><tr><td><code>option_default_value</code></td><td>string</td><td>Default value ID. Matches <code>value_id</code> in <code>option_values</code>.</td></tr><tr><td><code>show_option_value_qty</code></td><td>boolean</td><td>Whether to show a quantity input for each option value.</td></tr><tr><td><code>check_total_qty</code></td><td>boolean</td><td>Whether to validate total quantity.</td></tr><tr><td><code>is_onetime</code></td><td>boolean</td><td>Whether the charge is applied only once and not multiplied by product quantity.</td></tr><tr><td><code>addcharge_per_character</code></td><td>boolean</td><td>Whether to charge per entered character.</td></tr><tr><td><code>text_transform</code></td><td>string</td><td>Text transform setting. Accepted values: <code>uppercase</code>, <code>lowercase</code>, <code>capitalize</code>, or empty string.</td></tr><tr><td><code>hide_price</code></td><td>boolean</td><td>Whether to hide the displayed price.</td></tr><tr><td><code>option_url</code></td><td>string</td><td>URL behavior for the option. Accepted values: <code>none</code>, <code>group_product</code>, <code>only_url</code>, or <code>allowed_open_url</code>.</td></tr><tr><td><code>url_display</code></td><td>string</td><td>Controls how the URL is displayed or opened. Accepted values: <code>click_value</code> or <code>click_view</code>.</td></tr><tr><td><code>rich_text_value</code></td><td>string</td><td>Rich text content. Used by <code>paragraph</code> and <code>html</code>.</td></tr><tr><td><code>rich_text_value_modal</code></td><td>string</td><td>Rich text content for modal popup.</td></tr><tr><td><code>rich_text_value_size_chart</code></td><td>string</td><td>Rich text content for size chart.</td></tr><tr><td><code>editor_type</code></td><td>string</td><td>Editor type for modal. Accepted values: empty string for rich text or <code>code_editor</code>.</td></tr><tr><td><code>group_id</code></td><td>number</td><td>Group ID. Only available when <code>type = "option_group"</code>. Value is generated by <code>Date.now()</code>.</td></tr><tr><td><code>group_parent</code></td><td>string</td><td>Parent group ID. Only available when the option belongs to a group.</td></tr><tr><td><code>step_parent</code></td><td>string</td><td>Parent step ID. Only available when the option belongs to a step.</td></tr><tr><td><code>button</code></td><td>object</td><td>Button configuration. Example: <code>{ "button_type": "combine", "step_required": true }</code>.</td></tr><tr><td><code>dimension_price_total</code></td><td>string</td><td>Dimension-based pricing formula. Example: <code>x * {{price}}</code>.</td></tr><tr><td><code>conditional_logic</code></td><td>object</td><td>Conditional show/hide logic. See Conditional Logic.</td></tr><tr><td><code>slider</code></td><td>object</td><td>Slider configuration.</td></tr><tr><td><code>live_preview</code></td><td>object</td><td>Live preview configuration.</td></tr><tr><td><code>dimension_values</code></td><td>object</td><td>Dimension configuration.</td></tr><tr><td><code>inventory</code></td><td>object</td><td>Inventory configuration.</td></tr><tr><td><code>option_values</code></td><td>array</td><td>List of option values. See OptionValue object.</td></tr></tbody></table>

### URL-related fields

Use these fields when an option needs to work with product grouping or URL-based behavior.

<table><thead><tr><th width="141">Field</th><th width="196">Value</th><th>Description</th></tr></thead><tbody><tr><td><code>option_url</code></td><td><code>none</code></td><td>Default value when no URL behavior is selected.</td></tr><tr><td><code>option_url</code></td><td><code>group_product</code></td><td>Used for grouped product behavior.</td></tr><tr><td><code>option_url</code></td><td><code>only_url</code></td><td>The option only contains a URL.</td></tr><tr><td><code>option_url</code></td><td><code>allowed_open_url</code></td><td>Allows the URL to be opened.</td></tr><tr><td><code>url_display</code></td><td><code>click_value</code></td><td>The URL action is triggered when the customer clicks the option value.</td></tr><tr><td><code>url_display</code></td><td><code>click_view</code></td><td>The URL action is triggered when the customer clicks the view/open action.</td></tr></tbody></table>

***

## 11. OptionValue Object

`option_values[]` contains the selectable values of a choice-based option, such as radio, checkbox, dropdown, button, and swatch options.

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

<details>

<summary>View swatch JSON structure</summary>

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

</details>

<table><thead><tr><th width="202">Field</th><th width="140">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>color</code></td><td>string</td><td>Hex color. Example: <code>#FF0000</code>.</td></tr><tr><td><code>file_image</code></td><td>object</td><td>Uploaded file data used by the frontend.</td></tr><tr><td><code>file_image_url</code></td><td>string</td><td>Swatch image URL.</td></tr><tr><td><code>is_color</code></td><td>boolean</td><td>Whether the swatch displays a color or an image. <code>true</code> = color swatch, <code>false</code> = image swatch.</td></tr><tr><td><code>colors_number</code></td><td>string</td><td>Number of colors displayed. Accepted values: <code>one</code> or <code>two</code>.</td></tr></tbody></table>

***

## 12. Conditional Logic

Conditional logic controls whether an option is shown or hidden based on another option’s selected value.

<details>

<summary>View JSON structure</summary>

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

</details>

### Field descriptions

<table><thead><tr><th width="279">Field</th><th width="144">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>type</code></td><td>string</td><td>Action when the condition matches. Accepted values: <code>show</code> or <code>hide</code>.</td></tr><tr><td><code>logic</code></td><td>string</td><td>How conditions are combined. Accepted values: <code>all</code> for AND logic or <code>any</code> for OR logic.</td></tr><tr><td><code>condition_items[].field</code></td><td>string</td><td>Key of the controlling option used for comparison. This must match <code>options[].key</code>.</td></tr><tr><td><code>condition_items[].type</code></td><td>string</td><td>Condition operator. Examples: <code>contains</code>, <code>is</code>.</td></tr><tr><td><code>condition_items[].field_label</code></td><td>string</td><td>Display label of the controlling option. Used for reference only.</td></tr><tr><td><code>condition_items[].value</code></td><td>string or null</td><td>Comparison value. For selectable options, this usually matches <code>option_values[].value_id</code>.</td></tr></tbody></table>

<details>

<summary>Example: show engraving text only when engraving is selected</summary>

```json
{
  "type": "show",
  "logic": "all",
  "condition_items": [
    {
      "field": "engraving_option_key",
      "type": "contains",
      "field_label": "Add engraving?",
      "value": "yes_value_id"
    }
  ]
}
```

</details>

In this example:

* `field` = the `key` of the “Add engraving?” option.
* `value` = the `value_id` of the “Yes” option value.
* The target option will be shown only when the selected value contains `yes_value_id`.

***

## 13. Step Structure

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

<details>

<summary>View step JSON structure</summary>

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

</details>

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

***

## 14. Slider Structure

<details>

<summary>View slider JSON structure</summary>

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

</details>

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

***

## 15. Dimension Values Structure

<details>

<summary>View dimension values JSON structure</summary>

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

</details>

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

***

## 16. Inventory Structure

Inventory data is hydrated from a separate collection and is not stored directly inside `option_sets`.

<details>

<summary>View inventory JSON structure</summary>

```json
{
  "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": ""
    }
  ]
}
```

</details>

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

***

## 17. Option Type Enum

Valid values for `options[].type`.

### Input options

| 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.           |
| `hidden_field` | Hidden field.            |

### Choice options

| Type            | Description                        |
| --------------- | ---------------------------------- |
| `radio`         | Radio buttons. Single selection.   |
| `checkbox`      | Checkboxes. Multiple selection.    |
| `button_single` | Button option. Single selection.   |
| `button_multi`  | Button option. Multiple selection. |
| `select`        | Drop-down menu.                    |
| `combo_box`     | Combo box.                         |
| `combo_select`  | Combo dropdown.                    |

### Swatch options

| Type                  | Description                       |
| --------------------- | --------------------------------- |
| `swatch`              | Swatches, legacy or generic.      |
| `combo_color`         | Combo color.                      |
| `combo_image`         | Combo image.                      |
| `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.                   |

### Pricing, quantity, and configuration options

| Type        | Description                         |
| ----------- | ----------------------------------- |
| `switch`    | On/off toggle.                      |
| `slider`    | Numeric slider.                     |
| `quantity`  | Quantity input.                     |
| `dimension` | Dimension input, such as W × H × D. |

### Content and layout options

| Type           | Description        |
| -------------- | ------------------ |
| `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.      |

***

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

***

## 19. Important Notes

### Boolean-like values stored as strings

Some fields look like booleans but are returned as strings.

| Field            | Returned values       |
| ---------------- | --------------------- |
| `isValueActive`  | `"TRUE"` or `"FALSE"` |
| `allow_multiple` | `"true"` or `"false"` |
| `app_status`     | `"true"` or `"false"` |

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

### IDs

`key`, `option_id`, and `value_id` are usually 30-character nanoid strings. Some values may be UUID v4 values depending on data source or legacy data.

### Price

Price values are numbers and may contain decimals.

### Group ID

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

### Group and step parents

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

### Swatch types

* `is_color = true` means the swatch is a color swatch.
* `is_color = false` means the swatch is an image swatch.

***

## 20. Example: Option with Values

<details>

<summary>View option JSON example</summary>

```json
{
  "key": "color_option_key",
  "type": "swatch_single_color",
  "option_id": "color_option_id",
  "option_name": "Color",
  "label_product": "Choose your color",
  "label_cart": "Color",
  "required": true,
  "sort": 1,
  "option_values": [
    {
      "value_id": "red_value_id",
      "value": "Red",
      "type": "adjustprice",
      "isValueActive": "TRUE",
      "price": 5,
      "swatch": {
        "color": "#FF0000",
        "file_image": {},
        "file_image_url": "",
        "is_color": true,
        "colors_number": "one"
      }
    }
  ]
}
```

</details>

***

## 21. Example: Conditional Logic Between Two Options

<details>

<summary>View conditional logic JSON example</summary>

```json
{
  "key": "engraving_text_key",
  "type": "text",
  "option_name": "Engraving text",
  "label_product": "Enter engraving text",
  "required": false,
  "conditional_logic": {
    "type": "show",
    "logic": "all",
    "condition_items": [
      {
        "field": "add_engraving_key",
        "type": "contains",
        "field_label": "Add engraving?",
        "value": "yes_value_id"
      }
    ]
  }
}
```

In this example:

* `engraving_text_key` is the key of the option being controlled.
* `add_engraving_key` is the key of the controlling option.
* `yes_value_id` is the selected value ID that triggers the condition.

</details>

\---

## 22. Changelog

| Date       | Change                                                                                                                                                                                 |
| ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 2026-05-25 | Wrapped long examples, sample responses, and JSON structures in expandable sections for GitBook readability.                                                                           |
| 2026-05-25 | Added `option_url` and `url_display` fields with accepted values.                                                                                                                      |
| 2026-05-25 | Updated API host to `https://public-api.avisplus.io`, added Swagger URL, clarified token handling, clarified `field` vs `key` usage, reorganized option type enum, and added examples. |
| 2026-04-09 | Added the `translated` field to option set responses when the `locale` query parameter is provided.                                                                                    |
| 2026-04-06 | Released Public API v1 with option sets list/detail, settings, and localizations endpoints.                                                                                            |