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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://options-docs-v2.avisplus.io/integration/api-and-webview-reference.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.