API & Webview reference
Integrations

API & Webview reference

19 min read Updated Jul 24, 2026

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:

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

Currently, API/Webview tokens are generated and provided by the ArisPlus team. Merchants do not generate tokens directly from the app UI yet.

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:

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

Common error codes

Code Description
400 Bad request. Required query parameter is missing or invalid.
401 Missing authorization header or invalid API token.
403 The shop does not have an active subscription, or the app is uninstalled.
404 The requested resource does not exist.
429 Rate limit exceeded.
500 Server error.

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#

Method Endpoint Purpose
GET /api/public/v1/option-sets Retrieve a paginated list of option sets.
GET /api/public/v1/option-sets/:id Retrieve a single option set by ID.
GET /api/public/v1/settings Retrieve app settings for the authenticated shop.
GET /api/public/v1/localizations Retrieve localization strings for a specific locale.

6. List Option Sets#

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

GET /api/public/v1/option-sets

Query parameters

Parameter Type Required Description
page integer No Page number, 1-based. Default: 1.
limit integer No Number of results per page. Minimum: 1, maximum: 100. Default: 20.
status string No Filter by option set status. Accepts "true" for active option sets or "false" for inactive option sets.
product_id string No 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.
name string No Case-insensitive substring search by option set name. Example: color, wrap.
locale string No BCP 47 language code, for example en, vi, fr, or de. When provided, option labels and values are overlaid with translated values when available.

Sort order

The response is sorted by:

  1. sort ascending
  2. created_at descending
Example request
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>"
Response 200
{
  "shop": "my-store.myshopify.com",
  "data": [
    {
      "_id": "option_set_id",
      "option_set_name": "Gift Wrap Options",
      "status": true,
      "type": "manual",
      "all_products": false,
      "products": ["1234567890"],
      "options": [],
      "sort": 0,
      "created_at": "2026-04-06T00:00:00.000Z",
      "updated_at": "2026-04-09T00:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 58,
    "pages": 3
  }
}

data[] Option Set object

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

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.

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

Input

Parameter Type Required Description
id string Yes Path parameter. MongoDB ObjectId of the option set.
locale string No Query parameter. BCP 47 language code. When provided, option labels and values are overlaid with translated values when available.
Example request
curl -X GET "https://public-api.avisplus.io/api/public/v1/option-sets/option_set_id?locale=en" \
  -H "Authorization: Bearer <api-token>"
Response 200

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

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

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

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

8. Get Settings#

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

GET /api/public/v1/settings

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

Example request
curl -X GET "https://public-api.avisplus.io/api/public/v1/settings" \
  -H "Authorization: Bearer <api-token>"
Response 200
{
  "shop": "my-store.myshopify.com",
  "data": {
    "_id": "...",
    "app_status": "true",
    "use_css_version": "v2",
    "shopify_option": {},
    "show_add_charge_feat": true,
    "show_conditional_logic_feat": true
  }
}

Settings data

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

9. Get Localizations#

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

GET /api/public/v1/localizations

Query parameters

Parameter Type Required Description
locale string Yes BCP 47 language code. Examples: en, vi, fr, de. If this parameter is missing, the API returns 400.
Example request
curl -X GET "https://public-api.avisplus.io/api/public/v1/localizations?locale=en" \
  -H "Authorization: Bearer <api-token>"
Response 200
{
  "shop": "my-store.myshopify.com",
  "locale": "en",
  "has_overrides": true,
  "data": {
    "text_price_add": "+{price_add}",
    "text_alert_required_min_characters": "Minimum {min} characters required",
    "dynamic_checkout_notification": "Please select all required options",
    "text_total_price": "Total: {total}"
  }
}

Localization fields

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

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

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

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

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

URL-related fields

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

Field Value Description
option_url none Default value when no URL behavior is selected.
option_url group_product Used for grouped product behavior.
option_url only_url The option only contains a URL.
option_url allowed_open_url Allows the URL to be opened.
url_display click_value The URL action is triggered when the customer clicks the option value.
url_display click_view The URL action is triggered when the customer clicks the view/open action.

11. OptionValue Object#

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

Field Type Description
value_id string Unique value ID. Usually a 30-character nanoid.
value string Label displayed on the storefront. Examples: Red, Size M, Custom text.
type string Pricing type. See Value Type Enum.
isValueActive string Boolean-like string. Always "TRUE" for active or "FALSE" for disabled, not a boolean.
price number Fixed additional price. Decimal value. Example: 5.99.
percentageCharge number Percentage-based charge based on the original product price. Example: 10 means 10%.
option_show_price string Price display mode. Accepted values: only_value, only_label, both, or none.
productId string Linked Shopify product ID. Used for charge or bundle logic.
productVariationId string Linked Shopify variant ID.
productName string Linked product name.
variantId string Shopify variant ID.
variantName string Variant name.
variantBundleName string Variant name in bundle logic.
productBundleName string Product name in bundle logic.
handle string Shopify product handle.
is_product_bundle boolean Whether the value is part of bundle logic.
isAdd boolean Add charge flag.
variant_image string Variant image URL.
inventory_quantity number Cached inventory quantity from Shopify.
des_value string HTML description or tooltip content for the value.
swatch object Swatch display configuration.
View swatch JSON structure
{
  "color": "#FF0000",
  "file_image": {},
  "file_image_url": "https://...",
  "is_color": true,
  "colors_number": "one"
}
Field Type Description
color string Hex color. Example: #FF0000.
file_image object Uploaded file data used by the frontend.
file_image_url string Swatch image URL.
is_color boolean Whether the swatch displays a color or an image. true = color swatch, false = image swatch.
colors_number string Number of colors displayed. Accepted values: one or two.

12. Conditional Logic#

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

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

Field descriptions

Field Type Description
type string Action when the condition matches. Accepted values: show or hide.
logic string How conditions are combined. Accepted values: all for AND logic or any for OR logic.
condition_items[].field string Key of the controlling option used for comparison. This must match options[].key.
condition_items[].type string Condition operator. Examples: contains, is.
condition_items[].field_label string Display label of the controlling option. Used for reference only.
condition_items[].value string or null Comparison value. For selectable options, this usually matches option_values[].value_id.
Example: show engraving text only when engraving is selected
{
  "type": "show",
  "logic": "all",
  "condition_items": [
    {
      "field": "engraving_option_key",
      "type": "contains",
      "field_label": "Add engraving?",
      "value": "yes_value_id"
    }
  ]
}

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

View step JSON structure
{
  "items": [
    {
      "step_id": "string",
      "icon": "url",
      "name": "Step Name",
      "desc": "Description"
    }
  ],
  "layout": "step-dots"
}
Field Type Description
items array List of steps.
items[].step_id string Unique step ID.
items[].icon string Step icon URL.
items[].name string Step name.
items[].desc string Step description.
layout string Step layout style. Example: step-dots.

14. Slider Structure#

View slider JSON structure
{
  "status": false,
  "rows": 1,
  "per_row": 2.5,
  "show_icon": true,
  "show_dot": false
}
Field Type Description
status boolean Whether the slider configuration is enabled.
rows number Number of rows.
per_row number Number of items per row.
show_icon boolean Whether to show icons.
show_dot boolean Whether to show dots.

15. Dimension Values Structure#

View dimension values JSON structure
{
  "default": "66",
  "label": "Width",
  "X": {
    "label": "Width"
  },
  "Y": {
    "label": "Height"
  },
  "Z": {
    "label": "Depth"
  }
}
Field Type Description
default string Default dimension value.
label string Main dimension label.
X.label string Label for width.
Y.label string Label for height.
Z.label string Label for depth.

16. Inventory Structure#

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

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

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#

View option JSON example
{
  "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"
      }
    }
  ]
}

21. Example: Conditional Logic Between Two Options#

View conditional logic JSON example
{
  "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.

---

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.

Was this article helpful?

If you still need help, our support team is here for you.

Contact Support