Attribute
This article provides comprehensive information and documentation on a set of API methods specifically designed to handle product attributes. By leveraging these methods, users can retrieve, create, update, and search product attributes, allowing for seamless integration and management of product data within the system.
The article includes detailed explanations, parameter descriptions, and usage examples for each API method, empowering developers to effectively utilize the capabilities provided by the product attribute API.
Get Attributes
Attributes are features of the products. For example, a t-shirt has color, size, fabric, etc. as attributes; however, a mobile phone has camera resolution, screen brightness, memory and disk capacity, color etc. attributes.
You can query the attributes to get a list of defined attributes.
| Parameter | Data Type | In | Description |
api_token | string | header | The API key of the customer account |
limit | integer | query | Amount of line items per page that will be returned |
page | integer | query | Page number to return |
Request GET
GET request is used for retrieving attributes. Check Search-Attribute section for filtering options.
content_type header represents the response type.
Authorization header is a required header for authentication. You can retrieve api_token with login.
Accept-language header determines translatable fields responses.
Path: i1/attributes/
import requests
url = "https://{customer_api_url}/api/i1/attributes/"
api_token = "f532eXXXXXXXXXXXXXXXXX201XXXXX9332d"
headers = {
'content-type': 'application/json',
'Authorization': 'Token {}'.format(api_token),
'Accept-language':'en-us'
}
response = requests.get(url, headers=headers)
print(response.text)
Response
Resource properties are in Python format. The table below shows attribute properties. Every field has been explained in the description section of the table.
| Parameter | Data Type | Description |
| key | string | Attribute’s code |
| data_type | enum | Type of data the corresponding attribute contains. It could be text, email, text_area, date, datetime, boolean, valuelabel, dropdown, multiple, price, nested_object, image, file, model, bundle |
| value | string | Attribute's value |
| label | string | Attribute's label. It is used on the frontend |
| default_value | string | Default value of the attribute |
| is_required | boolean | Defines whether or not to leave this attribute blank when creating or updating the product |
| is_visible | boolean | Defines whether this attribute will appear on the backoffice panel |
| is_searchable | boolean | Defines whether search can be made with this attribute |
| is_filterable | boolean | Defines whether the value of this attribute can be filtered |
| is_variant | boolean | Defines whether this attribute is variantable or not. For example, if this parameter is True for the "size" attribute, there will be a variant based on this value among child products linked to the parent product: X size t-shirt, L size t-shirt etc. |
| is_variant_listable | boolean | Defines whether different variants of the same product will appear on the product listing page |
| name | string | Attribute name |
| is_form_required | boolean | Customer must fill in a form when adding a product with "is form required == True" to the cart |
| is_form_field_required | boolean | Defines whether the form field is required to fill |
| erp_code | string | The code of this attribute code in ERP |
| pre_attribute | boolean | Defines whether the attribute is used for pre products or products |
“count” shows how many attributes exist in the system.
“next” shows the next cursor url to retrieve the desired attributes.
“previous” shows the previous cursor url to retrieve the desired attribute.
“results” shows every attribute detail with detailed field descriptions.
{
"count": 1,
"next": null,
"previous": null,
"results": [
{
"id": 1457,
"key": "test_size_attribute2",
"data_type": {
"value": "dropdown",
"label": "dropdown",
},
"default_value": null,
"is_required": false,
"is_visible": false,
"is_searchable": false,
"is_filterable": false,
"is_variant": false,
"is_variant_listable": false,
"name": "test_size_attribute EN",
"is_form_required": false,
"is_form_field_required": false,
"erp_code": "erp_test_size_attribute_2",
"pre_attribute": false,
}
]
}
Request GET Instance
Retrieves an attribute with a unique identifier.
content_type header represents the response type.
Authorization header required header for authentication. You can retrieve api_token with login.
Accept-language header determines translatable fields responses.
Path: i1/attributes/<pk>/
import requests
url = "https://{customer_api_url}/api/i1/attributes/1457/"
api_token = "f532eXXXXXXXXXXXXXXXXX201XXXXX9332d"
headers = {
'content-type': 'application/json',
'Authorization': 'Token {}'.format(api_token),
'Accept-language':'en-us'
}
response = requests.get(url, headers=headers)
print(response.text)
Response
Shows the details of the attribute with a given unique identifier.
{
"id": 1457,
"key": "test_size_attribute2",
"data_type": dropdown,
"default_value": null,
"is_required": false,
"is_visible": false,
"is_searchable": false,
"is_filterable": false,
"is_variant": false,
"is_variant_listable": false,
"name": "test_size_attribute EN",
"is_form_required": false,
"is_form_field_required": false,
"erp_code": "erp_test_size_attribute_2",
"pre_attribute": false,
}
Search Attribute
GET requests can be filtered with parameters. You can search "attribute" according to these labels. All the below labels are acceptable as query parameters. For example, if you are looking for only required attributes, you need to send ‘?is_required=True’ at the end of the url.
| Parameter | Data Type | In | Description |
api_token | string | header | The API key of the customer account |
limit | integer | query | Amount of line items per page that will be returned |
page | integer | query | Page number to return |
| name | string | params | Attribute name |
| key | string | params | Attribute code |
| is_variant | boolean | params | True / False |
| is_searchable | boolean | params | True / False |
| is_visible | boolean | params | True / False |
| is_required | boolean | params | True / False |
| data_type | boolean | params | text, text_area, dropdown |
| is_localizable | boolean | params | True / False |
| is_variant_listable | boolean | params | True / False |
| modified_date__gt | datetime | params | Last updated date greater than |
| modified_date__lt | datetime | params | Last updated date lower than |
| modified_date__gte | datetime | params | Last updated date greater and equal than |
| modified_date__lte | datetime | params | Last updated date lower and equal than |
| modified_date__date__gt | date | params | Last updated date greater than |
| modified_date__date__lt | date | params | Last updated date lower than |
| modified_date__date__gte | date | params | Last updated date greater and equal than |
| modified_date__date__lte | date | params | Last updated date lower and equal than |
| accept-language | string | params | Language code (Ex: "en-us","tr-tr") |
Request GET
Retrieves attributes with filtered desired values. Below example shows filtering attributes with ‘attribute_name’.
‘content_type’ header represents the response type.
‘Authorization’ header is a required header for authentication. You can retrieve api_token with login.
‘Accept-language’ header determines translatable fields responses.
Path: attributes/
import requests
url = "https://{customer_api_url}/api/i1/attributes/?<attribute_name>=<attribute_value>"
api_token = "f532eXXXXXXXXXXXXXXXXX201XXXXX9332d"
headers = {
'content-type': 'application/json',
'Authorization': 'Token {}'.format(api_token),
'Accept-language':'en-us'
}
params = {
'key':'test_text_attribute',
'limit':'4',
'page':'1'
}
response = requests.get(url, headers=headers , params=params)
print(response.text)
Response
Response contains all attribute data with search parameters and with pagination. Response status is expected to be HTTP-200 Successful.
The table below shows attribute properties. Every field has been explained in the description section of the table.
Resource properties are in Python format.
| Parameter | Data Type | Description |
| ID | integer | Attribute identifier number |
| key | string | Attribute code |
| data_type | enum | Specifies the data type of the property. It can take the following values: text, text_area, dropdown |
| value | string | Attribute's value |
| label | string | Attribute's label. It is used on the frontend |
| default_value | string | Default value of the attribute |
| is_required | boolean | Defines whether or not to leave this attribute blank when creating or updating the product |
| is_visible | boolean | Defines whether this attribute will appear on the back office panel |
| is_searchable | boolean | Defines whether search can be made with this attribute |
| is_filterable | boolean | Defines whether the value of this attribute can be filtered |
| is_variant | boolean | Defines whether this attribute is variantable or not. For example, if this parameter is True for the "size" attribute, there will be a variant based on this value among child products linked to the parent product: X size t-shirt, L size t-shirt etc. |
| is_variant_listable | boolean | Defines whether different variants of the same product will appear on the product listing page |
| name | string | Attribute name |
| is_form_required | boolean | Customer must fill in a form when adding a product with "is form required == True" to the cart |
| is_form_field_required | boolean | Defines whether the form field is required to fill |
| erp_code | string | The code of this attribute code in ERP |
“count” shows how many attributes exist in the system.
“next” shows the next page url to retrieve the desired attribute.
“previous” shows the previous page url to retrieve the desired attribute.
“results” shows every attribute property with detailed field descriptions.
{
"count": 1,
"next": null,
"previous": null,
"results": [
{
"id": 1458,
"key": "test_text_attribute",
"data_type": {
"value": "text",
"label": "Text"
},
"default_value": null,
"is_required": false,
"is_visible": false,
"is_searchable": false,
"is_filterable": false,
"is_variant": false,
"is_variant_listable": false,
"name": "Dummy Size",
"is_form_required": false,
"is_form_field_required": false,
"erp_code": "erp_test_text_attribute",
"pre_attribute": false
}
]
}
Create Attribute
Attributes are features of the products. For example, a t-shirt has color, size, fabric, etc. as attributes; however, a mobile phone has camera resolution, screen brightness, memory and disk capacity, color etc. attributes.
You can query the attributes to get a list of defined attributes.
| Parameter | Data Type | In | Required | Description |
| api_token | string | header | YES | The API key of the customer account |
| default_value | string | body | The default value for the attribute. For example the default value for the size attribute is M. | |
| is_visible | boolean | body | (default True) Determines whether the attribute will appear on the website. "_False could be selected for attributes that will be used during the back office (Omnitron) and not used on the website. For example, ERP color code, ERP SKU, etc. | |
| data_type | string | body | YES | Specifies the data type of the property. It can take the following values: text, text_area, dropdown |
| translations | list | body | If the attribute has different language support, the names of the attribute used in different languages are listed under **translations**. Such as, "en-us": "name": "SIZE" | |
| description | string | body | Description of the attribute | |
| is_form_required | boolean | body | (default False) The customer needs to fill out a form when adding a product whose is_form_required value is True to the cart. Such as the name and note to be written on the jewelry, watches, wallets, flowers. | |
| is_form_field_required | boolean | body | (default False) Defines whether the fields in the form (associated with "is_form_required") shown to the customer are required. | |
| is_filterable | boolean | body | (default False) If the parameter is True, this attribute can be viewed in filters. | |
| is_searchable | boolean | body | (default True) If the parameter is True, the customer can search with the value of the attribute on the website. | |
| pre_attribute | boolean | body | (default False) The pre_attribute value True should be defined if the attributes integrated from the ERP are requested to be reviewed and approved before they are put into use. | |
| is_localizable | boolean | body | (default False) If the value of the attribute will be used in different languages, True must be entered. For example, if this value is True, the description attribute can be used like EN: This rug is made of polyester from recycled PET bottles, and NL: Dit vloerkleed is gemaakt van polyester van gerecyclede PET-flessen. | |
| key | string | body | YES | Unique attribute code |
| erp_code | string | body | YES | The attribute code included on ERP |
| is_variant | boolean | body | (default 'False') Defines whether the product can be variant or not via the attribute. For example, if is_variant is 'True'for the size attribute, it is possible to make variants such as X size sweater, L size sweater among child products connected to the same parent product. | |
| is_variant_listable | boolean | body | (default False) Determines whether different variants of the same product will appear on the product listing page. | |
| is_required | boolean | body | (default False) Defines whether the attribute is required. It determines whether the attribute value can be left blank when creating or updating the product. | |
| name | string | body | YES | Attribute name |
Request POST
In this example, the attribute will be created with a dropdown type and in Turkish ("tr-tr") which is Omnitron's default language.
Path: v1/attributes/
import requests
import json
url = "https://{customer_api_url}/api/i1/attributes/"
api_token = "f532eXXXXXXXXXXXXXXXXX201XXXXX9332d"
headers = {
'content-type': 'application/json',
'Authorization': 'Token {}'.format(api_token),
}
data = {
"key": "test_size_attribute2",
"data_type": "dropdown",
"default_value": None,
"is_required": False,
"is_visible": False,
"is_searchable": False,
"is_filterable": False,
"is_variant": False,
"is_variant_listable": False,
"name": "test_size_attribute",
"is_form_required": False,
"is_form_field_required": False,
"erp_code": "erp_test_size_attribute_2",
"pre_attribute": False,
"description": None
}
response = requests.post(url, headers=headers, data=json.dumps(data))
print(response.text)
Response
Shows the details of the attribute that was created.
{
"pk": 1457,
"key": "test_size_attribute2",
"data_type": "dropdown",
"default_value": null,
"is_required": false,
"is_visible": false,
"is_searchable": false,
"is_filterable": false,
"is_variant": false,
"is_variant_listable": false,
"name": "test_size_attribute",
"is_form_required": false,
"is_form_field_required": false,
"erp_code": "erp_test_size_attribute_2",
"pre_attribute": false,
"description": null,
"is_localizable": false
}
Language Support
Note: If Attribute type is ‘text’ or ‘textarea’ and the attribute will be used in different languages, is_localizable parameter should be _True. In order to send language translation for an attribute, the Accept-Language parameter needs to be added to the header. Accept-Language parameter is an optional parameter. If it is not sent, Omnitron's default language will be defined.
Request POST
In this example, the attribute will be created with text type and in Turkish ("tr-tr") which is Omnitron's default language.
Path: v1/attributes/
import requests
import json
url = "https://{customer_api_url}/api/v1/products/"
api_token = "f532eXXXXXXXXXXXXXXXXX201XXXXX9332d"
headers = {
'content-type': 'application/json',
'Authorization': 'Token {}'.format(api_token),
}
data = {
"key": "test_text_attribute",
"data_type": "text",
"default_value": None,
"is_localizable": True,
"is_required": False,
"is_visible": False,
"is_searchable": False,
"is_filterable": False,
"is_variant": False,
"is_variant_listable": False,
"name": "Dummy Size",
"is_form_required": False,
"is_form_field_required": False,
"erp_code": "erp_test_text_attribute",
"pre_attribute": False,
"description": None
}
response = requests.post(url, headers=headers, data=json.dumps(data))
print(response.text)
Response
Returns the created attribute data. Response status is expected to be HTTP-201 Created. “modified_date” and “created_date” parameters show the date when the attribute was last modified, and the date when it was created.
{
"pk": 1458,
"key": "test_text_attribute",
"data_type": "text",
"default_value": null,
"is_required": false,
"is_visible": false,
"is_searchable": false,
"is_filterable": false,
"is_variant": false,
"is_variant_listable": false,
"name": "Dummy Size",
"is_form_required": false,
"is_form_field_required": false,
"erp_code": "erp_test_text_attribute",
"pre_attribute": false,
"description": null,
"is_localizable": true
"modified_date": "2016-12-14T14:56:02.160001Z",
"created_date": "2016-12-14T14:56:02.160001Z",
}
Bad Request Responses
When the requested action cannot be executed, API gives an explanation about the request.
“islocalizable” property can be _True only if ‘data_type’ of an attribute is ‘text’ or ‘text_area’.
{
"non_field_errors": [
"is_localizable field cannot be True when Attribute data_type is not one of text or text area"]
}
“erp_code” is a unique field and doesn’t accept duplicate data.
{
"non_field_errors": "(erp_code:erp_color) is already exists",
"error_code": "attribute_200_1"
}
There are some reserved keys which cannot be used to create attributes. Reserved keys are Product model fields excluding description, brand, weight and tax_rate. Check the Product section to see the entire reserved key list.
{
"non_field_errors": "Requested key name cannot be used. modified_date is reserved.",
"error_code": "attribute_200_6"
}
Update Attribute
To update an attribute, it is necessary to know its ID. For example, you change the ‘isvisible’ parameter from _False to True. There are some restrictions with which you cannot perform an update. How to get ID and other details are explained under Search Attribute section.
| Parameter | Data Type | In | Description |
| api_token | string | header | The API key of the customer account |
| default_value | string | body | The default value for the attribute. For example, the default value for the size attribute is M. |
| is_visible | boolean | body | (default 'True') Determines whether the feature will appear on the website. 'False' could be selected for attributes that will be used at the back office (Omnitron) and not used on the website. For example, ERP color code, ERP SKU, etc. |
| data_type | string | body | Specifies the data type of the property. It can take the following values: text, text_area, dropdown |
| translations | list | body | If the attribute has different language support, the names of the attribute used in different languages are listed under translations. For example, `"en-us": "name": "SIZE"` . |
| description | sting | body | Description of attribute |
| is_form_required | boolean | body | (default 'False') The customer needs to fill out a form when adding a product whose is_form_required value is 'True' to the cart. Such as the name and note to be written on the jewelry, watches, wallets, flowers. |
| is_form_field_required | boolean | body | (default 'False') Defines whether the fields in the form (associated with "is_form_required") shown to the customer are required. |
| is_filterable | boolean | body | (default 'False') If the parameter is 'True', this attribute can be viewed in filters |
| is_searchable | boolean | body | (default 'True') If the parameter is 'True', the customer can search with the value of the attribute on the website |
| pre_attribute | boolean | body | (default 'False') The pre_attribute value 'True' should be defined if the attributes integrated from the ERP are requested to be reviewed and approved before they are put into use |
| is_localizable | boolean | body | (default 'False') If the value of the attribute will be used in different languages, 'True' must be entered. For example, if this value is 'True', the description attribute can be used as EN: This rug is made of polyester from recycled PET bottles, and NL: Dit vloerkleed is gemaakt van polyester van gerecyclede PET-flessen. |
| key | sting | body | Unique attribute code |
| erp_code | string | body | The attribute code included on ERP |
| is_variant | boolean | body | (default 'False') Defines whether the product can be variant or not via the attribute. For example, if is_variant is 'True' for the size attribute, it is possible to make variants such as X size sweater, L size sweater among child products connected to the same parent product. |
| is_variant_listable | boolean | body | (default 'False') Determines whether different variants of the same product will appear on the product listing page |
| is_required | boolean | body | (default 'False') Defines whether the attribute is required. It determines whether the attribute value can be left blank when creating or updating the product. |
| name | string | body | Attribute name |
| is_localizable | boolean | body | (default 'False') Defines whether the attribute is translatable or not. Only ‘text’ or ‘text_area’ type of attributes can be localizable |
Request PATCH
There are three sections of an update request. Url with instance ID, headers and data which can change the desired field(s) of an attribute.
‘content_type’ header represents the response type.
‘Authorization’ header is a required header for authentication. You can retrieve api_token with login.
Path: v1/attributes/<ATTRIBUTE_ID>
import requests
import json
url = "https://{customer_api_url}/api/i1/attributes/1457/"
api_token = "f532eXXXXXXXXXXXXXXXXX201XXXXX9332d"
headers = {
'content-type': 'application/json',
'Authorization': 'Token {}'.format(api_token),
}
cookies = {
'django_language':'en-us'
}
data = {
"key": "test_size_attribute2",
"data_type": "dropdown",
"name": "test_size_attribute EN"
}
response = requests.patch(url, headers=headers, cookies=cookies , data=json.dumps(data))
print(response.text)
Response
After the update is done, the response shows the updated data of the attribute.
‘created_date’ shows the date when the attribute was created.
‘modified_date’ shows the date of the last attribute update.
{
"pk": 1457,
"key": "test_size_attribute2",
"data_type": "dropdown",
"default_value": null,
"is_required": false,
"is_visible": false,
"is_searchable": false,
"is_filterable": false,
"is_variant": false,
"is_variant_listable": false,
"name": "test_size_attribute EN",
"is_form_required": false,
"is_form_field_required": false,
"erp_code": "erp_test_size_attribute_2",
"pre_attribute": false,
"description": null,
"modified_date": "2022-02-21T08:13:40.424413Z",
"created_date": "2016-12-14T14:56:02.160001Z,
"is_localizable: false
}
Bad Request Responses
When the requested action cannot be executed, API gives an explanation about the request.
{
"non_field_errors": "Data type can not be updated",
"error_code": "attribute_200_5"
}
If the ‘islocalizable’ field is _True, any Product has the attribute. ‘Islozalizable’ field cannot be updated to _False.
{
"non_field_errors": "Attribute is used by Product(s). Can not update is_localizable field!",
"error_code": "attribute_200_4"
}
If an attribute is used by any Product, the key field cannot be updated.
{
"non_field_errors": "Attribute is used by Product(s). Can not update attribute_key field!",
"error_code": "attribute_200_4"
}
There are some reserved keys which cannot be used to create attributes. Reserved keys are Product model fields excluding description, brand, weight and tax_rate. Check the Product section to see the entire reserved key list.
{
"non_field_errors": "Requested key name cannot be used. modified_date is reserved.",
"error_code": "attribute_200_6"
}