How to work with product attributes, options, and variants
1. How to work with product attributes
An attribute is a parameter or a characteristic of a product, like size or color. The administrator of the store sets attribute value.
Attribute types
- General attributes are present on any platform, for any product by default. For example, NAME, DESCRIPTION, MODEL, PRICE. In the rare case when platforms don’t support some general attribute, we return “null” in the corresponding response field.
- Additional attributes are present only on some particular platform. For example, Woocommerce has viewed_count and ordered_count attributes, Magento has country_of_manufacture.
For methods product.info and product.list, additional attributes are returned the same way as general - as fields of structure product.
In the response of API v1.1 additional fields are returned in additional_fields array.
- Custom attributes are specifically created on one particular store for all or some of the products.
Custom attributes can be divided into custom attributes of the product (are created and used for one specific product) or system custom attributes (are created on the store level and can be applied to all or some products).
For example, TV can have custom attributes like display size, screen resolution, etc.
API requests for working with attributes
Methods: product.list; product info
Fields: product, product.additional_fields, product.custom_fields
Use methods and fields above for getting names and values of all attributes of a product of any type.
Method: product.attribute.list
Use product.attribute.list to get not only attribute value, but also additional attribute parameters, like
- if the attribute field is required
- value type (string, boolean, etc., depending on the platform)
- sort position and others.
Method: product.attribute.value.set
Use product.attribute.value.set to set value of particular attribute for the specific product. If the product doesn’t have such an attribute, it will be created.
How to add simple products with global and custom attributes
Let's say you need to add product with attribute value “Color” = “Green” and “Pattern” = “Stripes”
For this, make the following requests:
And then make 1 product.attribute.value.set request for each attribute, if needed.
For updating existing attributes it is best to use product.attribute.value.set method. If a product doesn’t have the attribute yet, then it will be created, but there are some limitations on some platforms.
- Shopify - no limitations
- Prestashop - if the global attribute with the needed name exists, then there will be created custom attribute with the same name.
- Magento - if the global attribute with the needed name already exists, then the product should be in the same attribute set as the product. Otherwise, the request will return error.
- Bigcommerce - not supported
- Woocommerce - not supported
How to get info on product attributes
All attributes of the product, both custom and global, can be accessed via product.list/product.info.
To make sure you get all product attributes, join arrays “additional_fields” and “custom_fields” from the response, because on different platforms attributes are stored in either first or the second array.
2. How to work with product options, option values
Options are product attributes that can be changed (selected) by store clients to choose specific product variant.
For example, option “Size” may have option values, like “Small”, “Medium”, etc.
The combination is the combination of all option values of a product (if it has a few value options).
API requests for working with options
Product.list; product.info
Field: product_options
Options are returned with all available values (product_options.option_items).
On some platforms, like WooCommerce, Magento, Opencart, etc. there are price modifiers that allow setting how the end price depends on option_value selection (price modifier, the field product_options.option_items.price).
The following methods work for Magento and Opencart:
- product.option.add
- product.option.assign
- product.option.value.add
- product.option.value.assign
3. How to work with configurable (variable) products, product variants
Configurable products (WooCommerce calls them “Variable”, Prestashop - "Product with combinations") let sellers offer a set of variations on a product, with control over prices, stock, image and more for each variation.
The shopper chooses the combination of options, and based on this the store suggests him some product variant, like “T-Shirt, green, medium size”. Store owner can set price, stock, image and other attributes for each variant.
On some platforms, like WooCommerce seller should always specify all possible attributes when editing the variant. However, if there is a possibility not to specify some attribute values, we exclude this attribute from combinations and variants.
There is a special type of options - custom options. When shopper chooses these custom options values, the product variant doesn’t change. For example, “T-Shirt, green, medium size” may have custom option “with/without printing”, but the choice of this option doesn’t change the product variant, it will stay the same in the shopping cart or order. Custom options are accessed the same as ordinary ones.
Methods to work with variants:
- product.variant.add
- product.variant.update
To form a variant, in those methods in the attribute parameter, you need to specify option values that are part of a combination and price modifier for each value.
On some platforms, like Shopify and Magento 2, price modifiers don’t count. Instead, price of the variant should be specified in the price parameter.
Example of request with price modifier
Example of request without price modifier
Method variant.add will also create options and option values specified in the attributes field (if the product was “simple” before (didn’t have options).
Methods to get info on variants:
- product.child_item.list
- product.child_item.list
- product.child_item.find
Deprecated methods for working with variants:
- product.variant.delete
- product.variant.list
- product.variant.info
How to add configurable product T-Shirt with 4 variants
Red T-Shirt size M
Green T-Shirt size M
Red T-Shirt size S
Green T-Shirt size S
Step 1: Add parent product
Step 2: Add parent product variants
How to get some order product info?
(e.g. the real-time product quantity in the store)
Step 1: Pay attention to the variant_id field in the response structure of order.info or order.list methods.
If the field is empty, then the order contains a simple product. If it is filled, then it means that some variant of configurable product is ordered.
Response example (part)
...
"order_products": [
{
"product_id": "3121496555620",
"order_product_id": "2611044286564",
"model": "963852",
"name": "1111 - L / red / cotton",
"price": 94.117647058824,
"price_inc_tax": 100,
"quantity": 1,
"discount_amount": 0,
"total_price": 100,
"tax_percent": 6.25,
"tax_value": 5.8823529411765,
"tax_value_after_discount": 5.88,
"variant_id": "25625890914404"
...
Step 2: If the field is empty, then you should use product.info method and specify product_id from the response above.
https://api.api2cart.com/v1.1/product.info.json?api_key=API_KEY&store_key=STORE_KEY&id=3121496555620
Step 3: If the field is not empty, then you should save from the response above field values product_id and variant_id.
Get info on product variants with saved product_id and specify product_id parameter.
Step 3.1: From children field choose variant with “id” that is identical to “variant_id” from the previous response.
NOTICE
Child_item.list and product.info methods can show an error message that the product is not found. It means that at the current time the product can not exist, but it was when the order was placed.
