> ## Knowledge Base Index > Fetch the complete knowledge base index at: https://help.linkedoption.com/sitemap.xml > Use this file to discover available pages before exploring further. > Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash). # Product Group API Guide Our Product Groups API enables seamless integration with your existing systems, making it easier than ever to create, update, delete, and retrieve product groups. With its simple and secure design, the API helps you automate workflows, maintain consistent data across platforms, and streamline your overall product management process. The API is available only on **Premium plan and above**. You can use it for free on development stores. ## Support For technical support or questions about the API, contact us at: [[email protected]](https://helpkit.getalltool.com/support%2525252525252525252525252525252525252525252525252525252525252525252525252525252525252525252525252525252525252525252525252525252525252525252525252525252525252525252525252525252525252525252525252525252525252525252525252525252525252540getalltool.com) ## Authentication The API uses **Shop Domain** and **API Key** to authenticate requests. They can be found in *Settings > Manage product groups by API*: All API requests require the following header for authentication: ``` { "Content-Type": "application/json", "X-SHOP-DOMAIN": "Your domain, xxx.myshopify", "X-API-KEY": "YOUR_API_KEY" } ``` **NOTE:** `X-SHOP-DOMAIN`  must be myshopify domain, for example: `SHOPNAME.myshopify.com` **Authenticated request:** ``` curl -i -H "X-SHOP-DOMAIN: $SHOP_DOMAIN" \ -H "X-API-KEY: $API_KEY" \ "https://api.linkedoption.com/v1/groups ``` ## **Base URL**  https://api.linkedoption.com/v1 ## Endpoints ### 1. List all groups Returns a paginated list of groups. **Endpoint:** `GET /v1/groups` **Query Parameters:** * **page** (integer, optional, default:1): Page number for pagination. * **page_size** (integer, optional, default: 10, max_value: 100): Number of items per page. **Example Request:** ``` curl -i -H "X-SHOP-DOMAIN: $SHOP_DOMAIN" \ -H "X-API-KEY: $API_KEY" \ "https://api.linkedoption.com/v1/groups?page=1&page_size=10" ``` ### 2. Get Product Group by ID Retrieve a single product group by its group ID. **Endpoint:** `GET /v1/groups/:id` **URL Parameters:** * `id` (string, required): The group ID of the product group (e.g., `100`). **Example Request:** ``` curl -i -H "X-SHOP-DOMAIN: $SHOP_DOMAIN" \ -H "X-API-KEY: $API_KEY" \ "https://api.linkedoption.com/v1/groups/100" ``` ### 3. Create a single option group Create a single option group with specified products. Returns the created group ID. **Endpoint:** `POST /v1/groups/single` **Body (JSON)**: * **group_name** (string, required): The name of the group, used internally. * **status** (string, optional): The status of the group. Defaults to `ACTIVE`. * Available values: `ACTIVE`, `DRAFT`. * **option_name** (string, required): The name of the option. * **template_id** (integer, required): The template for the product group. * **card_selector_type** (string, required, default: DEFAULT): Defines the option display style on the product card. Allowed values: * **DEFAULT**: The product card option type follows the template’s option type. *For example, if the template uses a color-swatch type, the product card will also display it as a color swatch.* * **IMAGE_SWATCH**: Render the option as an image swatch on the product card. * **COLOR_SWATCH**: Render the option as a color swatch on the product card. * **BUTTON**: Render the option as a button on the product card. * **DROPDOWN**: Render the option as a dropdown menu on the product card. * **hide_in_card** (boolean, optional): Whether to hide this option on the product card. * **products** (array, required): A list of product configurations. * **id** (string, required): Shopify product ID - a numeric string like "14824372961343". You can find this ID in your Shopify admin URL when viewing a product: *https://admin.shopify.com/store/your-store-name/products/14824372961343* * **option_value** (object, required): Configuration for the option value. * **value** (string, required): The option value for the product. * **color_type** (string, optional): The color type for color swatches. Required when using a color swatch template. Allowed values: * **one_color**: A single solid color. * **two_color**: A two-color split swatch. * **custom_image**: A custom image used to represent complex colors or patterns. * **color_one** (string, optional): A valid color value (e.g., `#FFFFFF`). Required when *color_type* is *one_color* or *two_color*. * **color_two** (string, optional): A valid color value (e.g., `#F1F1F1`). Required when *color_type* is *two_color*. * **color_image** (string, optional): A valid public image URL used *only* when *color_type* is *custom_image*. This image replaces a color swatch and is typically used to represent complex colors or patterns. * **image** (string, optional): A publicly accessible image URL used when the option is displayed as an image swatch. If omitted, the system will automatically use the product’s first image as the default swatch image. * **badge** (string, optional): A badge label for the option value (e.g., “10 off”, “Sale”). **Example body:** ``` { "group_name": "Baby Socks", "status": "ACTIVE", "option_name": "Style", "template_id": "3", "card_selector_type": "DEFAULT", "hide_in_card": true, "products": [ { "id": "8224593641628", "option_value": { "value": "Deer", "color_type": "one_color", "color_one": "#e66565", "color_two": "", "color_image": "", "image": "https://thumbnail.getalltool.com/lo/king-linked-options-dev.myshopify.com/b3ad478e483865844be93a7d7b925d12.jpg", "badge": "20%" } }, { "id": "8224594591900", "option_value": { "value": "Eagle", "color_type": "one_color", "color_one": "#b4b4b4", "color_two": "", "color_image": "", "image": "https://thumbnail.getalltool.com/lo/king-linked-options-dev.myshopify.com/e75a3a8eaef01c8978072cb39f60c1f1.jpg", "badge": "" } }, { "id": "8224593576092", "option_value": { "value": "Fox", "color_type": "one_color", "color_one": "#72d433", "color_two": "", "color_image": "", "image": "https://thumbnail.getalltool.com/lo/king-linked-options-dev.myshopify.com/3655f419c39afa28d1cf39c9589d231c.jpg", "badge": "" } } ] } ``` **Example request:** ``` curl -i -H "X-SHOP-DOMAIN: $SHOP_DOMAIN" \ -H "X-API-KEY: $API_KEY" \ -H "Content-Type: application/json" \ -d '{"group_name":"Baby Socks","status":"ACTIVE","option_name":"Style","template_id":"3","card_selector_type":"DEFAULT","hide_in_card":true,"products":[{"id":"8224593641628","option_value":{"value":"Deer","color_type":"one_color","color_one":"#e66565","color_two":"","color_image":"","image":"https://thumbnail.getalltool.com/lo/king-linked-options-dev.myshopify.com/b3ad478e483865844be93a7d7b925d12.jpg","badge":"20%"}},{"id":"8224594591900","option_value":{"value":"Eagle","color_type":"one_color","color_one":"#b4b4b4","color_two":"","color_image":"","image":"https://thumbnail.getalltool.com/lo/king-linked-options-dev.myshopify.com/e75a3a8eaef01c8978072cb39f60c1f1.jpg","badge":""}},{"id":"8224593576092","option_value":{"value":"Fox","color_type":"one_color","color_one":"#72d433","color_two":"","color_image":"","image":"https://thumbnail.getalltool.com/lo/king-linked-options-dev.myshopify.com/3655f419c39afa28d1cf39c9589d231c.jpg","badge":""}}]}' \ -X POST "https://api.linkedoption.com/v1/groups/single" ``` ### 4. Update a single option group Create a single option group with specified products. Returns the created group ID. **Endpoint:** `PUT /v1/groups/single/:id` **URL Parameters:** * `id` (string, required): The group ID of the product group (e.g., `100`). **Body (JSON):** The body structure is consistent with the endpoint for creating a single-option product group. **Example request:** ``` curl -i -H "X-SHOP-DOMAIN: $SHOP_DOMAIN" \ -H "X-API-KEY: $API_KEY" \ -H "Content-Type: application/json" \ -d '{"group_name":"Baby Socks","status":"ACTIVE","option_name":"Style","template_id":"3","card_selector_type":"DEFAULT","hide_in_card":true,"products":[{"id":"8224593641628","option_value":{"value":"Deer","color_type":"one_color","color_one":"#e66565","color_two":"","color_image":"","image":"https://thumbnail.getalltool.com/lo/king-linked-options-dev.myshopify.com/b3ad478e483865844be93a7d7b925d12.jpg","badge":"20%"}},{"id":"8224594591900","option_value":{"value":"Eagle","color_type":"one_color","color_one":"#b4b4b4","color_two":"","color_image":"","image":"https://thumbnail.getalltool.com/lo/king-linked-options-dev.myshopify.com/e75a3a8eaef01c8978072cb39f60c1f1.jpg","badge":""}},{"id":"8224593576092","option_value":{"value":"Fox","color_type":"one_color","color_one":"#72d433","color_two":"","color_image":"","image":"https://thumbnail.getalltool.com/lo/king-linked-options-dev.myshopify.com/3655f419c39afa28d1cf39c9589d231c.jpg","badge":""}}]}' \ -X PUT https://api.linkedoption.com/v1/groups/single/100 ``` ### 5. Create a multi-option group Create a single option group with specified products. Returns the created group ID. **Endpoint:** `POST /v1/groups/multi` **Body (JSON)**: * **group_name** (string, required): The name of the group, used internally. * **status** (string, optional): The status of the group. Defaults to `ACTIVE`. * Available values: `ACTIVE`, `DRAFT`. * **hide_in_card** (boolean, optional): Whether to hide this option on the product card. * **options** (array, required): Option list * **name** (string, required): Option name or label * **template_id** (integer, required): The template for the option * **card_selector_type** (string, required, default: DEFAULT): Defines the option display style on the product card. Allowed values: * **DEFAULT**: The product card option type follows the template’s option type. *For example, if the template uses a color-swatch type, the product card will also display it as a color swatch.* * **IMAGE_SWATCH**: Render the option as an image swatch on the product card. * **COLOR_SWATCH**: Render the option as a color swatch on the product card. * **BUTTON**: Render the option as a button on the product card. * **DROPDOWN**: Render the option as a dropdown menu on the product card. * values (array, required): Option values * **value** (string, required): The option value for the product. * **color_type** (string, optional): The color type for color swatches. Required when using a color swatch template. Allowed values: * **one_color**: A single solid color. * **two_color**: A two-color split swatch. * **custom_image**: A custom image used to represent complex colors or patterns. * **color_one** (string, optional): A valid color value (e.g., `#FFFFFF`). Required when *color_type* is *one_color* or *two_color*. * **color_two** (string, optional): A valid color value (e.g., `#F1F1F1`). Required when *color_type* is *two_color*. * **color_image** (string, optional): A valid public image URL used *only* when *color_type* is *custom_image*. This image replaces a color swatch and is typically used to represent complex colors or patterns. * **image** (string, optional): A publicly accessible image URL used when the option is displayed as an image swatch. If omitted, the system will automatically use the product’s first image as the default swatch image. * **badge** (string, optional): A badge label for the option value (e.g., “10 off”, “Sale”). * products (array, required): A list of product configurations. * **id** (string, required): Shopify product ID - a numeric string like "14824372961343". You can find this ID in your Shopify admin URL when viewing a product: *https://admin.shopify.com/store/your-store-name/products/14824372961343* * **variant** (array, required): Option value combinations, e.g., ["Red", "M"]. **Example body:** ``` { "group_name": "Kids Socks", "hide_in_card": false, "status": "ACTIVE", "options": [ { "name": "Style", "template_id": "3", "card_selector_type": "DEFAULT", "values": [ { "value": "Lace", "color_type": "one_color", "color_one": "#b53e3e", "color_two": "#1c5fd8", "color_image": "", "image": "https://thumbnail.getalltool.com/lo/king-linked-options-dev.myshopify.com/adb9c45aba74d0d00eaf454fbb35831c.jpg", "badge": "" }, { "value": "Fashion Letter", "color_type": "one_color", "color_one": "#b53e3e", "color_two": "#1c5fd8", "color_image": "", "image": "https://thumbnail.getalltool.com/lo/king-linked-options-dev.myshopify.com/2529b7127623e9311723b401aa324856.jpg", "badge": "" }, { "value": "Mixed", "color_type": "one_color", "color_one": "#b53e3e", "color_two": "#1c5fd8", "color_image": "", "image": "https://thumbnail.getalltool.com/lo/king-linked-options-dev.myshopify.com/cd011d7102d9ff36518b857e1c77bc16.jpg", "badge": "" } ] }, { "name": "Color", "template_id": "8", "card_selector_type": "DEFAULT", "values": [ { "value": "Yellow", "color_type": "one_color", "color_one": "#ecff00", "color_two": "#1c5fd8", "image": "", "badge": "" }, { "value": "Blue", "color_type": "two_color", "color_one": "#0076ff", "color_two": "red", "color_image": "", "image": "", "badge": "" }, { "value": "Mixed", "color_type": "custom_image", "color_one": "#b53e3e", "color_two": "#1c5fd8", "color_image": "https://thumbnail.getalltool.com/lo/king-linked-options-dev.myshopify.com/3beefc6f5fafb489d0379f0063eb39d0.webp", "image": "", "badge": "" } ] }, { "name": "Size", "template_id": "7", "card_selector_type": "DEFAULT", "values": [ { "value": "S", "color_type": "one_color", "color_one": "#b53e3e", "color_two": "#1c5fd8", "color_image": "", "image": "", "badge": "" }, { "value": "M", "color_type": "one_color", "color_one": "#b53e3e", "color_two": "#1c5fd8", "color_image": "", "image": "", "badge": "" }, { "value": "L", "color_type": "one_color", "color_one": "#b53e3e", "color_two": "#1c5fd8", "color_image": "", "image": "", "badge": "" } ] } ], "products": [ { "id": "8224677068956", "variant": [ "Lace", "Yellow", "M" ] }, { "id": "8224592953500", "variant": [ "Fashion Letter", "Blue", "L" ] }, { "id": "8224592887964", "variant": [ "Fashion Letter", "Blue", "M" ] }, { "id": "8224678051996", "variant": [ "Fashion Letter", "Blue", "S" ] }, { "id": "8224592593052", "variant": [ "Fashion Letter", "Yellow", "L" ] }, { "id": "8224593084572", "variant": [ "Fashion Letter", "Yellow", "M" ] }, { "id": "8224678412444", "variant": [ "Fashion Letter", "Yellow", "S" ] }, { "id": "8224591577244", "variant": [ "Lace", "Blue", "L" ] }, { "id": "8224591478940", "variant": [ "Lace", "Blue", "M" ] }, { "id": "8224591413404", "variant": [ "Lace", "Blue", "S" ] }, { "id": "8224591610012", "variant": [ "Lace", "Yellow", "L" ] }, { "id": "8224677167260", "variant": [ "Lace", "Yellow", "S" ] }, { "id": "8224677626012", "variant": [ "Mixed", "Yellow", "S" ] } ] } ``` **Example request:** ``` curl -i -H "X-SHOP-DOMAIN: $SHOP_DOMAIN" \ -H "X-API-KEY: $API_KEY" \ -H "Content-Type: application/json" \ -d '{"group_name":"Kids Socks","hide_in_card":false,"status":"ACTIVE","options":[{"name":"Style","template_id":"3","card_selector_type":"DEFAULT","values":[{"value":"Lace","color_type":"one_color","color_one":"#b53e3e","color_two":"#1c5fd8","color_image":"","image":"https://thumbnail.getalltool.com/lo/king-linked-options-dev.myshopify.com/adb9c45aba74d0d00eaf454fbb35831c.jpg","badge":""},{"value":"Fashion Letter","color_type":"one_color","color_one":"#b53e3e","color_two":"#1c5fd8","color_image":"","image":"https://thumbnail.getalltool.com/lo/king-linked-options-dev.myshopify.com/2529b7127623e9311723b401aa324856.jpg","badge":""},{"value":"Mixed","color_type":"one_color","color_one":"#b53e3e","color_two":"#1c5fd8","color_image":"","image":"https://thumbnail.getalltool.com/lo/king-linked-options-dev.myshopify.com/cd011d7102d9ff36518b857e1c77bc16.jpg","badge":""}]},{"name":"Color","template_id":"8","card_selector_type":"DEFAULT","values":[{"value":"Yellow","color_type":"one_color","color_one":"#ecff00","color_two":"#1c5fd8","image":"","badge":""},{"value":"Blue","color_type":"two_color","color_one":"#0076ff","color_two":"red","color_image":"","image":"","badge":""},{"value":"Mixed","color_type":"custom_image","color_one":"#b53e3e","color_two":"#1c5fd8","color_image":"https://thumbnail.getalltool.com/lo/king-linked-options-dev.myshopify.com/3beefc6f5fafb489d0379f0063eb39d0.webp","image":"","badge":""}]},{"name":"Size","template_id":"7","card_selector_type":"DEFAULT","values":[{"value":"S","color_type":"one_color","color_one":"#b53e3e","color_two":"#1c5fd8","color_image":"","image":"","badge":""},{"value":"M","color_type":"one_color","color_one":"#b53e3e","color_two":"#1c5fd8","color_image":"","image":"","badge":""},{"value":"L","color_type":"one_color","color_one":"#b53e3e","color_two":"#1c5fd8","color_image":"","image":"","badge":""}]}],"products":[{"id":"8224677068956","variant":["Lace","Yellow","M"]},{"id":"8224592953500","variant":["Fashion Letter","Blue","L"]},{"id":"8224592887964","variant":["Fashion Letter","Blue","M"]},{"id":"8224678051996","variant":["Fashion Letter","Blue","S"]},{"id":"8224592593052","variant":["Fashion Letter","Yellow","L"]},{"id":"8224593084572","variant":["Fashion Letter","Yellow","M"]},{"id":"8224678412444","variant":["Fashion Letter","Yellow","S"]},{"id":"8224591577244","variant":["Lace","Blue","L"]},{"id":"8224591478940","variant":["Lace","Blue","M"]},{"id":"8224591413404","variant":["Lace","Blue","S"]},{"id":"8224591610012","variant":["Lace","Yellow","L"]},{"id":"8224677167260","variant":["Lace","Yellow","S"]},{"id":"8224677626012","variant":["Mixed","Yellow","S"]}]}' \ -X POST https://api.linkedoption.com/v1/groups/multi ``` #### Optional subcategories within Multi Option options Both `POST /v1/groups/multi` and `PUT /v1/groups/multi/:id` accept the following **optional** fields. They group values inside an option; they do not create an additional option dimension and do not use the separate `/groups/subcategory` endpoint. | Field | Type | Description | | --- | --- | --- | | `options[].value_grouping` | object, optional | Subcategory configuration for this option. Omit it for regular options. | | `value_grouping.version` | integer | Must be `1` when the configuration is supplied. | | `value_grouping.enabled` | boolean | `true` enables grouping; `false` displays a flat list while retaining the supplied category configuration. | | `value_grouping.categories` | array | Ordered categories. When enabled, supply 2–49 categories. | | `categories[].key` | string | Unique, nonblank identifier within this option, up to 128 characters. Keep it stable when renaming a category. | | `categories[].name` | string | Display label, up to 255 characters after trimming. When enabled, names must be nonblank and unique (case-insensitive). | | `options[].values[].category_key` | string, optional | Identifier of the category containing this value. Must match a category key; if supplied, it must be 1–128 characters. | **Existing integrations do not need to change their requests.** - **Create without these fields:** creates a regular Multi Option group. - **Update without these fields:** retains saved category configuration for options with the same name. Existing value assignments are matched by value name; keep option and value names unchanged to preserve their assignments. - **Omitted assignment while grouping is enabled:** an existing matching value retains its valid assignment; a new or unassigned value goes into the first category. - **Explicit assignment:** sending `category_key` moves the value into that category. Send keys that exist in the supplied or saved configuration. - **Disable grouping:** send the full `value_grouping` object with `enabled: false` and the categories you want to retain. Omitting `value_grouping` does not disable existing grouping. - Invalid configurations or category references return **400 Bad Request**. Do not send `null` or empty strings in place of omitted fields. **Example body for create or update:** Replace the sample template IDs and product IDs with IDs from your shop. This example groups Color while Size remains a regular option. `products[].variant` still contains option values in option order, without category names. ```json { "group_name": "Sports shorts", "status": "ACTIVE", "hide_in_card": false, "options": [ { "name": "Color", "template_id": 8, "value_grouping": { "version": 1, "enabled": true, "categories": [ { "key": "core", "name": "Core" }, { "key": "limited", "name": "Limited Editions" } ] }, "values": [ { "value": "Dark green", "color_type": "one_color", "color_one": "#336666", "category_key": "core" }, { "value": "Red", "color_type": "one_color", "color_one": "#B33B3B", "category_key": "limited" } ] }, { "name": "Size", "template_id": 7, "values": [{ "value": "S" }, { "value": "M" }] } ], "products": [ { "id": "123456789", "variant": ["Dark green", "S"] }, { "id": "123456790", "variant": ["Red", "M"] } ] } ``` For the admin workflow and screenshots, see [Organize Multi Option values into subcategories](https://help.linkedoption.com/en/article/organize-multi-option-values-into-subcategories-1pycw5v/). ### 6. Update a multi-option group Create a single option group with specified products. Returns the created group ID. **Endpoint:** `PUT /v1/groups/multi/:id` **URL Parameters:** * `id` (string, required): The group ID of the product group (e.g., `100`). **Body (JSON)**: The body structure is consistent with the endpoint for creating a multi-option product group. **Example request:** ``` curl -i -H "X-SHOP-DOMAIN: $SHOP_DOMAIN" \ -H "X-API-KEY: $API_KEY" \ -H "Content-Type: application/json" \ -d '{"group_name":"Kids Socks","hide_in_card":false,"status":"ACTIVE","options":[{"name":"Style","template_id":"3","card_selector_type":"DEFAULT","values":[{"value":"Lace","color_type":"one_color","color_one":"#b53e3e","color_two":"#1c5fd8","color_image":"","image":"https://thumbnail.getalltool.com/lo/king-linked-options-dev.myshopify.com/adb9c45aba74d0d00eaf454fbb35831c.jpg","badge":""},{"value":"Fashion Letter","color_type":"one_color","color_one":"#b53e3e","color_two":"#1c5fd8","color_image":"","image":"https://thumbnail.getalltool.com/lo/king-linked-options-dev.myshopify.com/2529b7127623e9311723b401aa324856.jpg","badge":""},{"value":"Mixed","color_type":"one_color","color_one":"#b53e3e","color_two":"#1c5fd8","color_image":"","image":"https://thumbnail.getalltool.com/lo/king-linked-options-dev.myshopify.com/cd011d7102d9ff36518b857e1c77bc16.jpg","badge":""}]},{"name":"Color","template_id":"8","card_selector_type":"DEFAULT","values":[{"value":"Yellow","color_type":"one_color","color_one":"#ecff00","color_two":"#1c5fd8","image":"","badge":""},{"value":"Blue","color_type":"two_color","color_one":"#0076ff","color_two":"red","color_image":"","image":"","badge":""},{"value":"Mixed","color_type":"custom_image","color_one":"#b53e3e","color_two":"#1c5fd8","color_image":"https://thumbnail.getalltool.com/lo/king-linked-options-dev.myshopify.com/3beefc6f5fafb489d0379f0063eb39d0.webp","image":"","badge":""}]},{"name":"Size","template_id":"7","card_selector_type":"DEFAULT","values":[{"value":"S","color_type":"one_color","color_one":"#b53e3e","color_two":"#1c5fd8","color_image":"","image":"","badge":""},{"value":"M","color_type":"one_color","color_one":"#b53e3e","color_two":"#1c5fd8","color_image":"","image":"","badge":""},{"value":"L","color_type":"one_color","color_one":"#b53e3e","color_two":"#1c5fd8","color_image":"","image":"","badge":""}]}],"products":[{"id":"8224677068956","variant":["Lace","Yellow","M"]},{"id":"8224592953500","variant":["Fashion Letter","Blue","L"]},{"id":"8224592887964","variant":["Fashion Letter","Blue","M"]},{"id":"8224678051996","variant":["Fashion Letter","Blue","S"]},{"id":"8224592593052","variant":["Fashion Letter","Yellow","L"]},{"id":"8224593084572","variant":["Fashion Letter","Yellow","M"]},{"id":"8224678412444","variant":["Fashion Letter","Yellow","S"]},{"id":"8224591577244","variant":["Lace","Blue","L"]},{"id":"8224591478940","variant":["Lace","Blue","M"]},{"id":"8224591413404","variant":["Lace","Blue","S"]},{"id":"8224591610012","variant":["Lace","Yellow","L"]},{"id":"8224677167260","variant":["Lace","Yellow","S"]},{"id":"8224677626012","variant":["Mixed","Yellow","S"]}]}' \ -X PUT https://api.linkedoption.com/v1/groups/multi/101 ``` ### 7. Create a subcategory group Create a single option group with specified products. Returns the created group ID. **Endpoint:** `POST /v1/groups/subcategory` **Body (JSON)**: * **group_name** (string, required): The name of the group, used internally. * **status** (string, optional): The status of the group. Defaults to `ACTIVE`. * Available values: `ACTIVE`, `DRAFT`. * **template_id** (integer, required): The template for the product group. * **card_selector_type** (string, required, default: DEFAULT): Defines the option display style on the product card. Allowed values: * **DEFAULT**: The product card option type follows the template’s option type. *For example, if the template uses a color-swatch type, the product card will also display it as a color swatch.* * **IMAGE_SWATCH**: Render the option as an image swatch on the product card. * **COLOR_SWATCH**: Render the option as a color swatch on the product card. * **BUTTON**: Render the option as a button on the product card. * **DROPDOWN**: Render the option as a dropdown menu on the product card. * **hide_in_card** (boolean, optional): Whether to hide this option on the product card. * **subcategories** (array, required): Subcategory * **option_name** (string, required): The name of the option. * **products** (array, required): A list of product configurations. * **id** (string, required): Shopify product ID - a numeric string like "14824372961343". You can find this ID in your Shopify admin URL when viewing a product: *https://admin.shopify.com/store/your-store-name/products/14824372961343* * **option_value** (object, required): Configuration for the option value. * **value** (string, required): The option value for the product. * **color_type** (string, optional): The color type for color swatches. Required when using a color swatch template. Allowed values: * **one_color**: A single solid color. * **two_color**: A two-color split swatch. * **custom_image**: A custom image used to represent complex colors or patterns. * **color_one** (string, optional): A valid color value (e.g., `#FFFFFF`). Required when *color_type* is *one_color* or *two_color*. * **color_two** (string, optional): A valid color value (e.g., `#F1F1F1`). Required when *color_type* is *two_color*. * **color_image** (string, optional): A valid public image URL used *only* when *color_type* is *custom_image*. This image replaces a color swatch and is typically used to represent complex colors or patterns. * **image** (string, optional): A publicly accessible image URL used when the option is displayed as an image swatch. If omitted, the system will automatically use the product’s first image as the default swatch image. * **badge** (string, optional): A badge label for the option value (e.g., “10 off”, “Sale”). **Example body:** ``` { "group_name": "test", "status": "ACTIVE", "template_id": "9", "hide_in_card": true, "card_selector_type": "DEFAULT", "subcategories": [ { "option_name": "Core", "products": [ { "id": "8272380559516", "option_value": { "value": "Black", "color_type": "one_color", "color_one": "#1c1c1c", "color_two": "", "color_image": "", "image": "https://thumbnail.getalltool.com/lo/king-linked-options-dev.myshopify.com/6119862748b6bd0c94da7e9fa0a3a376.jpg", "badge": "test" } }, { "id": "8272380657820", "option_value": { "value": "Brown", "color_type": "two_color", "color_one": "#5a3a2a", "color_two": "#111111", "color_image": "", "image": "https://thumbnail.getalltool.com/lo/king-linked-options-dev.myshopify.com/aeda296bba710bbef30d700af1584f03.jpg", "badge": "" } }, { "id": "8272380723356", "option_value": { "value": "Burgundy", "color_type": "custom_image", "color_one": "#763346", "color_two": "", "color_image": "https://thumbnail.getalltool.com/lo/king-linked-options-dev.myshopify.com/ccef00bb16dd935d6e7707070ae260fe.jpg", "image": "https://thumbnail.getalltool.com/lo/king-linked-options-dev.myshopify.com/ccef00bb16dd935d6e7707070ae260fe.jpg", "badge": "" } } ] }, { "option_name": "Limited Editions", "template_id": "8", "card_selector_type": "DEFAULT", "products": [ { "id": "8272381214876", "option_value": { "value": "Light Yellow", "color_type": "one_color", "color_one": "#cfd2c0", "color_two": "", "color_image": "", "image": "https://thumbnail.getalltool.com/lo/king-linked-options-dev.myshopify.com/6e72e579f90df2555f19d247173139f0.jpg", "badge": "" } }, { "id": "8272381280412", "option_value": { "value": "Lilac", "color_type": "one_color", "color_one": "#a584d8", "color_two": "", "color_image": "", "image": "https://thumbnail.getalltool.com/lo/king-linked-options-dev.myshopify.com/ad427b734333661e9bb4bd7a0394a329.jpg", "badge": "" } }, { "id": "8272380461212", "option_value": { "value": "Lime Green", "color_type": "one_color", "color_one": "#86e245", "color_two": "", "color_image": "", "image": "https://thumbnail.getalltool.com/lo/king-linked-options-dev.myshopify.com/b008bbd41e7d4e057f44f250abbc3b09.jpg", "badge": "" } }, { "id": "8272381411484", "option_value": { "value": "Lvory", "color_type": "one_color", "color_one": "#d7dbdb", "color_two": "", "color_image": "", "image": "https://thumbnail.getalltool.com/lo/king-linked-options-dev.myshopify.com/6326fddd9d4151949f016d6e57975f25.jpg", "badge": "" } } ] } ] } ``` **Example request:** ``` curl -i -H "X-SHOP-DOMAIN: $SHOP_DOMAIN" \ -H "X-API-KEY: $API_KEY" \ -H "Content-Type: application/json" \ -d '{"group_name":"test","status":"ACTIVE","template_id":"9","hide_in_card":true,"card_selector_type":"DEFAULT","subcategories":[{"option_name":"Core","products":[{"id":"8272380559516","option_value":{"value":"Black","color_type":"one_color","color_one":"#1c1c1c","color_two":"","color_image":"","image":"https://thumbnail.getalltool.com/lo/king-linked-options-dev.myshopify.com/6119862748b6bd0c94da7e9fa0a3a376.jpg","badge":"test"}},{"id":"8272380657820","option_value":{"value":"Brown","color_type":"two_color","color_one":"#5a3a2a","color_two":"#111111","color_image":"","image":"https://thumbnail.getalltool.com/lo/king-linked-options-dev.myshopify.com/aeda296bba710bbef30d700af1584f03.jpg","badge":""}},{"id":"8272380723356","option_value":{"value":"Burgundy","color_type":"custom_image","color_one":"#763346","color_two":"","color_image":"https://thumbnail.getalltool.com/lo/king-linked-options-dev.myshopify.com/ccef00bb16dd935d6e7707070ae260fe.jpg","image":"https://thumbnail.getalltool.com/lo/king-linked-options-dev.myshopify.com/ccef00bb16dd935d6e7707070ae260fe.jpg","badge":""}}]},{"option_name":"Limited Editions","template_id":"8","card_selector_type":"DEFAULT","products":[{"id":"8272381214876","option_value":{"value":"Light Yellow","color_type":"one_color","color_one":"#cfd2c0","color_two":"","color_image":"","image":"https://thumbnail.getalltool.com/lo/king-linked-options-dev.myshopify.com/6e72e579f90df2555f19d247173139f0.jpg","badge":""}},{"id":"8272381280412","option_value":{"value":"Lilac","color_type":"one_color","color_one":"#a584d8","color_two":"","color_image":"","image":"https://thumbnail.getalltool.com/lo/king-linked-options-dev.myshopify.com/ad427b734333661e9bb4bd7a0394a329.jpg","badge":""}},{"id":"8272380461212","option_value":{"value":"Lime Green","color_type":"one_color","color_one":"#86e245","color_two":"","color_image":"","image":"https://thumbnail.getalltool.com/lo/king-linked-options-dev.myshopify.com/b008bbd41e7d4e057f44f250abbc3b09.jpg","badge":""}},{"id":"8272381411484","option_value":{"value":"Lvory","color_type":"one_color","color_one":"#d7dbdb","color_two":"","color_image":"","image":"https://thumbnail.getalltool.com/lo/king-linked-options-dev.myshopify.com/6326fddd9d4151949f016d6e57975f25.jpg","badge":""}}]}]}' \ -X POST https://api.linkedoption.com/v1/group/subcategory ``` ### 8. Update a subcategory group Create a single option group with specified products. Returns the created group ID. **Endpoint:** `PUT /v1/groups/subcategory/:id` **URL Parameters:** * `id` (string, required): The group ID of the product group (e.g., `100`). **Body (JSON)**: The body structure is consistent with the endpoint for creating a subcategory product group. **Example request:** ``` curl -i -H "X-SHOP-DOMAIN: $SHOP_DOMAIN" \ -H "X-API-KEY: $API_KEY" \ -H "Content-Type: application/json" \ -d '{"group_name":"test","status":"ACTIVE","template_id":"9","hide_in_card":true,"card_selector_type":"DEFAULT","subcategories":[{"option_name":"Core","products":[{"id":"8272380559516","option_value":{"value":"Black","color_type":"one_color","color_one":"#1c1c1c","color_two":"","color_image":"","image":"https://thumbnail.getalltool.com/lo/king-linked-options-dev.myshopify.com/6119862748b6bd0c94da7e9fa0a3a376.jpg","badge":"test"}},{"id":"8272380657820","option_value":{"value":"Brown","color_type":"two_color","color_one":"#5a3a2a","color_two":"#111111","color_image":"","image":"https://thumbnail.getalltool.com/lo/king-linked-options-dev.myshopify.com/aeda296bba710bbef30d700af1584f03.jpg","badge":""}},{"id":"8272380723356","option_value":{"value":"Burgundy","color_type":"custom_image","color_one":"#763346","color_two":"","color_image":"https://thumbnail.getalltool.com/lo/king-linked-options-dev.myshopify.com/ccef00bb16dd935d6e7707070ae260fe.jpg","image":"https://thumbnail.getalltool.com/lo/king-linked-options-dev.myshopify.com/ccef00bb16dd935d6e7707070ae260fe.jpg","badge":""}}]},{"option_name":"Limited Editions","template_id":"8","card_selector_type":"DEFAULT","products":[{"id":"8272381214876","option_value":{"value":"Light Yellow","color_type":"one_color","color_one":"#cfd2c0","color_two":"","color_image":"","image":"https://thumbnail.getalltool.com/lo/king-linked-options-dev.myshopify.com/6e72e579f90df2555f19d247173139f0.jpg","badge":""}},{"id":"8272381280412","option_value":{"value":"Lilac","color_type":"one_color","color_one":"#a584d8","color_two":"","color_image":"","image":"https://thumbnail.getalltool.com/lo/king-linked-options-dev.myshopify.com/ad427b734333661e9bb4bd7a0394a329.jpg","badge":""}},{"id":"8272380461212","option_value":{"value":"Lime Green","color_type":"one_color","color_one":"#86e245","color_two":"","color_image":"","image":"https://thumbnail.getalltool.com/lo/king-linked-options-dev.myshopify.com/b008bbd41e7d4e057f44f250abbc3b09.jpg","badge":""}},{"id":"8272381411484","option_value":{"value":"Lvory","color_type":"one_color","color_one":"#d7dbdb","color_two":"","color_image":"","image":"https://thumbnail.getalltool.com/lo/king-linked-options-dev.myshopify.com/6326fddd9d4151949f016d6e57975f25.jpg","badge":""}}]}]}' \ -X PUT "https://api.linkedoption.com/v1/groups/subcategory/102" ``` ### 9. Delete groups Create a single option group with specified products. Returns the created group ID. **Endpoint:** `DELETE /v1/groups` **Body (JSON)**: * **group_ids** (array, required): The name of the group, used internally. **Example body:** ``` { "group_ids": [ 1, 2, 3, 4, 5 ] } ``` **Example request:** ``` curl -i -H "X-SHOP-DOMAIN: $SHOP_DOMAIN" \ -H "X-API-KEY: $API_KEY" \ -H "Content-Type: application/json" \ -d '{"group_ids":[1,2,3,4]}' \ -X DELETE "https://api.linkedoption.com/v1/groups" ``` ### **10. Get supported languages and markets** Retrieve the languages and markets currently supported by the shop. **Endpoint:** `GET /v1/localizations` **Example Request:** ``` curl -i -H "X-SHOP-DOMAIN: $SHOP_DOMAIN" \ -H "X-API-KEY: $API_KEY" \ "https://api.linkedoption.com/v1/localizations" ``` Example Response: ``` { "code": 0, "msg": "ok", "data": { "languages": [ { "locale": "en", "name": "English", "primary": true, "published": true }, { "locale": "fr", "name": "French", "primary": false, "published": true } ], "markets": [ { "id": "123456789", "name": "France", "locales": [ "fr" ] } ] } } ``` Notes: * `languages` contains the shop languages available for translations. * `markets` contains Shopify Markets. Use the market `id` when querying or updating market-specific translations. * If `market` is omitted or empty in translation APIs, the translation applies to all markets. ### **11. Get product group translations** Retrieve product group translation keys and their translated values for a specified language and optional market. **Endpoint:** `GET /v1/translations` **Query Parameters:** * **translate_to** (string, required): Target locale, for example, fr, de, or pt-BR. * **market** (string, optional): Shopify Market ID. Leave empty to query translations for all markets. You can use the numeric market ID returned by `/v1/localizations`. * **page** (integer, optional, default: 1): Page number for pagination. * **page_size** (integer, optional, default: 15, max_value: 100): Number of items per page. * **status** (string, optional): Translation filter. * Available values: `translated`, `not_translated`, `all`. * **query** (string, optional): Search keyword for source text. * **refresh** (boolean, optional): Whether to refresh translation keys before querying. Available values: 1, 0, true, false. **Validation:** * `translate_to` must be an existing published shop locale. * If `market` is provided, it must be an existing market for the shop. * If the selected market has locale restrictions, `translate_to` it must be enabled for that market. * If `market` is empty, `translate_to` cannot be the primary shop locale. **Example Request without market:** ``` curl -i -H "X-SHOP-DOMAIN: $SHOP_DOMAIN" \ -H "X-API-KEY: $API_KEY" \ "https://api.linkedoption.com/v1/translations?translate_to=fr&page=1&page_size=15" ``` **Example Response:** ``` { "code": 0, "msg": "ok", "data": { "total": 2, "pageSize": 15, "translations": { "Color": "Couleur", "Red": "Rouge" } } } ``` Notes: * The keys in `data.translations` are source texts used in product groups. * Empty values mean the source text has not been translated for the selected language and market. ### **12. Update product group translations** Create, update, or remove product group translations for a specified language and optional market. **Endpoint:** `POST /v1/translations` **Body (JSON):** * **translate_to** (string, required): Target locale, for example `fr`, `de`, or `pt-BR`. * **market** (string, optional): Shopify Market ID. Leave empty to update translations for all markets. * **translations** (array, required): A list of translations to update. * **source** (string, required): Source text from product group translation keys. * **translate** (string, required): Translated value. Use an empty string to remove the translation. **Validation:** * `translate_to` must be an existing published shop locale. * If `market` is provided, it must be an existing market for the shop. * If the selected market has locale restrictions, `translate_to` must be enabled for that market. * If `market` is empty, `translate_to` cannot be the primary shop locale. * `translations` must be a non-empty array with up to 1000 items. * Each `source` must be an existing product group translation key for the shop. **Example Body:** ``` { "translate_to": "fr", "market": "123456789", "translations": [ { "source": "Color", "translate": "Couleur" }, { "source": "Red", "translate": "Rouge" } ] } ``` **Example Body without market:** ``` { "translate_to": "fr", "market": "", "translations": [ { "source": "Color", "translate": "Couleur" } ] } ``` **Example Request:** ``` curl -i -H "X-SHOP-DOMAIN: $SHOP_DOMAIN" \ -H "X-API-KEY: $API_KEY" \ -H "Content-Type: application/json" \ -d '{"translate_to":"fr","market":"123456789","translations":[{"source":"Color","translate":"Couleur"},{"source":"Red","translate":"Rouge"}]}' \ -X POST "https://api.linkedoption.com/v1/translations" ``` **Example Response:** ``` { "code": 0, "msg": "ok", "data": {} } ``` **Notes:** * Updating translations will enqueue synchronization tasks to publish the translated product group content to Shopify. * To delete a translation value, send the same source with translate as an empty string. ## Errors Errors are returned with standard HTTP status codes and a JSON body: ``` { "message": "Detailed error message", "errors": [] } ``` Common HTTP status codes: * `400 Bad Request`: Invalid request body or parameters. * `401 Unauthorized`: Missing or invalid API key. * `403 Forbidden`: Insufficient permissions. * `404 Not Found`: Resource not found. * `500 Internal Server Error`: Server-side error. ## Rate Limiting To maintain optimal performance for every user, the API applies rate limiting. If your requests exceed the allowed threshold, the server will return a **429 Too Many Requests** response. Should this occur, simply pause briefly before sending more requests.