Product Options
Product Options
Products in CS-Cart and Multi-Vendor can have options—additional properties that customers may select when buying a product. For example, for clothes that would be color, size, optional accessories, etc.
List Options of a Product¶
To get a list of options of a specific product, send a GET request to /api/options/?product_id=:id. For example:
GET /api/options/?product_id=12
If the request is successful, you’ll receive HTTP/1.1 200 OK and JSON with the options of the product.
Response Format¶
{
"3": {
"option_id": "3",
"product_id": "12",
"company_id": "1",
"option_type": "S",
"inventory": "Y",
"regexp": "",
"required": "N",
"multiupload": "N",
"allowed_extensions": "",
"max_file_size": "0",
"missing_variants_handling": "M",
"status": "A",
"position": "20",
"value": "",
"option_name": "Size",
"option_text": "Size",
"description": "",
"inner_hint": "",
"incorrect_message": "",
"comment": "",
"variants": {
"12": {
"variant_id": "12",
"option_id": "3",
"position": "10",
"modifier": "0.000",
"modifier_type": "A",
"weight_modifier": "0.000",
"weight_modifier_type": "A",
"point_modifier": "0.000",
"point_modifier_type": "A",
"variant_name": "Small",
"image_pair": []
},
"13": {
"variant_id": "13",
"option_id": "3",
"position": "20",
"modifier": "0.000",
"modifier_type": "A",
"weight_modifier": "0.000",
"weight_modifier_type": "A",
"point_modifier": "0.000",
"point_modifier_type": "A",
"variant_name": "Medium",
"image_pair": []
},
"14": {
"variant_id": "14",
"option_id": "3",
"position": "30",
"modifier": "0.000",
"modifier_type": "A",
"weight_modifier": "0.000",
"weight_modifier_type": "A",
"point_modifier": "0.000",
"point_modifier_type": "A",
"variant_name": "Large",
"image_pair": []
},
"15": {
"variant_id": "15",
"option_id": "3",
"position": "40",
"modifier": "0.000",
"modifier_type": "A",
"weight_modifier": "0.000",
"weight_modifier_type": "A",
"point_modifier": "0.000",
"point_modifier_type": "A",
"variant_name": "X Large",
"image_pair": []
},
"16": {
"variant_id": "16",
"option_id": "3",
"position": "50",
"modifier": "0.000",
"modifier_type": "A",
"weight_modifier": "0.000",
"weight_modifier_type": "A",
"point_modifier": "0.000",
"point_modifier_type": "A",
"variant_name": "XX Large",
"image_pair": []
}
}
},
"4": {
"option_id": "4",
"product_id": "12",
"company_id": "1",
"option_type": "S",
"inventory": "Y",
"regexp": "",
"required": "N",
"multiupload": "N",
"allowed_extensions": "",
"max_file_size": "0",
"missing_variants_handling": "M",
"status": "A",
"position": "0",
"value": "",
"option_name": "Color",
"option_text": "",
"description": "",
"inner_hint": "",
"incorrect_message": "",
"comment": "",
"variants": {
"17": {
"variant_id": "17",
"option_id": "4",
"position": "0",
"modifier": "0.000",
"modifier_type": "A",
"weight_modifier": "0.000",
"weight_modifier_type": "A",
"point_modifier": "0.000",
"point_modifier_type": "A",
"variant_name": "Black/White/White",
"image_pair": {
"pair_id": "805",
"image_id": "861",
"detailed_id": "0",
"position": "0",
"icon": {
"image_path": "http://localhost/images/variant_image/0/173283_01.jpg",
"alt": "",
"image_x": "500",
"image_y": "500",
"http_image_path": "http://localhost/images/variant_image/0/173283_01.jpg",
"https_image_path": "https://localhost/images/variant_image/0/173283_01.jpg",
"absolute_path": "/var/www/html/images/variant_image/0/173283_01.jpg",
"relative_path": "variant_image/0/173283_01.jpg"
}
}
},
"18": {
"variant_id": "18",
"option_id": "4",
"position": "0",
"modifier": "0.000",
"modifier_type": "A",
"weight_modifier": "0.000",
"weight_modifier_type": "A",
"point_modifier": "0.000",
"point_modifier_type": "A",
"variant_name": "Dark Navy/White/White",
"image_pair": {
"pair_id": "806",
"image_id": "862",
"detailed_id": "0",
"position": "0",
"icon": {
"image_path": "http://localhost/images/variant_image/0/242265_01.jpg",
"alt": "",
"image_x": "500",
"image_y": "500",
"http_image_path": "http://localhost/images/variant_image/0/242265_01.jpg",
"https_image_path": "https://localhost/images/variant_image/0/242265_01.jpg",
"absolute_path": "/var/www/html/images/variant_image/0/242265_01.jpg",
"relative_path": "variant_image/0/242265_01.jpg"
}
}
},
"19": {
"variant_id": "19",
"option_id": "4",
"position": "0",
"modifier": "0.000",
"modifier_type": "A",
"weight_modifier": "0.000",
"weight_modifier_type": "A",
"point_modifier": "0.000",
"point_modifier_type": "A",
"variant_name": "White/Prime Green",
"image_pair": {
"pair_id": "807",
"image_id": "863",
"detailed_id": "0",
"position": "0",
"icon": {
"image_path": "http://localhost/images/variant_image/0/X29580_01.jpg",
"alt": "",
"image_x": "500",
"image_y": "500",
"http_image_path": "http://localhost/images/variant_image/0/X29580_01.jpg",
"https_image_path": "https://localhost/images/variant_image/0/X29580_01.jpg",
"absolute_path": "/var/www/html/images/variant_image/0/X29580_01.jpg",
"relative_path": "variant_image/0/X29580_01.jpg"
}
}
}
}
}
}
Get a Specific Option¶
To get the details of a specific option, send a GET request to /api/options/<option_id>. For example:
GET /api/options/3
If the request is successful, you’ll receive HTTP/1.1 200 OK and JSON with the details of the option.
Option Details¶
The fields below represent various option details.
Note
The CS-Cart/Multi-Vendor REST API always accepts and returns data as strings and arrays/objects. The Values column in the table merely shows what kind of data you can expect in the fields.
| Field | Values | Description |
|---|---|---|
| option_id | integer | A unique identifier of the option. |
| product_id | integer | A unique identifier of the product that the option is associated with. |
| company_id | integer | ID of the associated storefront (in CS-Cart) or vendor (in Multi-Vendor). |
| option_type | string |
The type of the option:
S—select boxR—radiogroupC—checkboxI—text (one line)T—text areaF—file |
| inventory |
Y—yesN—no |
If enabled, the option is taken into account when forming the product inventory. |
| regexp | string |
If the option type is Text or Text area, you can use regular expressions to limit what users can enter in the field.
Note: If the
incorrect_message field is empty, the check for regular expressions won’t run. |
| required |
Y—yesN—no |
If an option is required, customers won’t be able to add a product to cart without specifying this option. For example, if a checkbox has required=Y, a customer must tick it before adding the product to cart. |
| multiupload |
Y—yesN—no |
If the option type is File, you can choose whether to allow customers to upload multiple files. |
| allowed_extensions | string | If the option type is File, you can specify the allowed extensions separated by commas (e.g. jpg,bmp,gif,pdf). |
| max_file_size | integer | The maximum size of the uploaded files (in kilobytes). |
| missing_variants_handling | string |
If the option type is Select box or Radiogroup, you can specify the variants of the option that customers can choose from. This field determines what to do when the administrator didn’t create variants for the option.
M—display a message next to the option name. By default the message is “N/A”H—hide this option |
| status | string |
The status of the option:
A—activeD—disabled |
| position | integer | This parameter determines the position of the option among other options. The lower this number, the higher the option appears on the list of options in the Administration panel. |
| value | string | The number of the option variant or the text entered in the field of Text or Text area option by the customers. |
| option_name | string | The name of the option. |
| description | string | If you fill in this field, the ? icon (tooltip) will appear near the option name on the product page. When you hover your mouse over the icon, you’ll see the description text. |
| inner_hint | string | A hint that appears in the field of a Text or Text area option. It tells the customers what they should enter in the field. The hint doesn’t serve as a default value. |
| incorrect_message | string | If you use regexp for Text or Text area options, this message appears when the entered text doesn’t conform to the regular expression. |
| comment | string | The text that appears below the option on the storefront. |
| variants | object | The variants of the option. Variants are available to the options of the Select box or Radiogroup type. An option of the Checkbox type has 2 variants by default. |
Option Variants¶
A Selectbox or Radiogroup option can have different variants for the customer to choose from. These variants appear in the variants object.
| Field | Values | Description |
|---|---|---|
| variant_id | integer | A unique identifier of the option variant. |
| option_id | integer | The ID of the option that the variant is associated with. |
| position | integer | The position of the variant among other variants. The lower this number, the higher the variant appears on the list of variants in the Administration panel. |
| modifier | float | The price modifier of the option variant. |
| modifier_type | string |
The type of the price modifier:
A—absolute: change product price by a fixed amount in the store’s primary currencyP—percentage: change product price by certain percentage |
| weight_modifier | float | The weight modifier of the option variant. |
| weight_modifier_type | string |
The type of the weight modifier:
A—absolute: change product weight by a fixed amount in the store’s weight measurement unitsP—percentage: change product weight of a product by certain percentage |
| point_modifier | float |
The reward point modifier of the option variant.
The Reward Points add-on allows your customers to earn points for purchasing products. These points can later be used to pay for other products.
|
| point_modifier_type | string |
The type of the reward point modifier:
A—absolute: change the number of points by a fixed amountP—percentage: change the number of points by certain percentage |
| variant_name | string | The name of the option variant. |
| image_pair | object | The information about the image of the option variant. |
Create an Option¶
To create an option, send a POST request to /api/options/.
Pass the fields with the option details in the HTTP request body in accordance with the passed Content-Type. Required fields are marked with *:
-
product_id*—the unique identifier of the product that the option is associated with.
-
option_name*—the name of the option.
-
option_type—the type of the option:
S—select boxR—radiogroupC—checkboxI—text (one line)T—text areaF—file
Note
If you don’t specify
option_typein the POST request, it will be set toSby default. -
required—determines if customers must specify this option before they can add the product to cart. Pass
Yfor “Yes” andNfor “No”. -
inventory—determines if the option is taken into account when forming the product inventory. Pass
Yfor Yes andNfor No. -
main_pair—an object with the icons of the option variants.
-
Any other fields that apply to the option of a particular type.
Example JSON:
{
"product_id": "12",
"option_name": "Packaging",
"option_type": "R",
"required": "Y",
"inventory": "N",
"main_pair": {
"icon": {
"image_path": {
"1": "http://example.com/image1.jpg",
"2": "http://example.com/image2.jpg"
}
}
},
"variants": {
"1": {
"variant_name": "None"
},
"2": {
"variant_name": "Gift wrap",
"modifier_type":"A",
"modifier":"5"
}
}
}
This request creates a new option for the product with product_id=12:
- The option is called Packaging.
- It has the Radiogroup type.
- It has 2 variants, both with icons. These variants are:
- None—doesn’t change the price of the product.
- Gift wrap—increases the price of the product by $5 (if the primary currency of your store is U.S. dollar).
If the option is created successfully, you will receive HTTP/1.1 201 Created and the option ID in the response:
{
"option_id": 27
}
Update an Option¶
To update an existing option, send the PUT request to /api/options/<option_id>/. For example:
PUT /api/options/27
Pass the fields with option details in the HTTP request body in accordance with the passed Content-Type. None of the fields are required.
Example JSON:
{
"option_type": "S",
"main_pair": {
"icon": {
"image_path": {
"2": "http://example.com/image3.jpg",
"3": "http://example.com/image4.jpg"
}
}
},
"variants": {
"2": {
"variant_name": "Gift wrap"
},
"3": {
"variant_name": "Present box",
"modifier_type":"P",
"modifier":"20"
}
}
}
This request changes the variant icons and variant types of the option with option_id=27. When we first created this option (Packaging), it had the Radiogroup type and 2 variants: None and Gift Wrap.
Here we change the option type to Select box—it supports variants as well. We didn’t pass None this time, so this variant is removed. Gift wrap doesn’t change. We also add a new variant called Present box. Choosing this variant will increase the price of the product by 20%.
Note
If an option has multiple variants, make sure to specify them all when you update the variants object with the PUT request. Variants that are not specified in the PUT request will be deleted.
Delete an Option¶
To delete an option, send the DELETE request to /api/options/<option_id>:
DELETE /api/options/27
This request will delete the specified option.
Possible responses:
- HTTP/1.1 204 No Content—the option has been deleted successfully.
- HTTP/1.1 400 Bad Request—the option couldn’t be deleted.
- HTTP/1.1 404 Not Found—the option doesn’t exist.
