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’s 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’s 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’s 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 ‘text_area’ 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.

“is_localizable” 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 ‘is_visible’ 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.

api_token	string	header	The API key of the customer’s 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 ‘is_localizable’ field is True, any Product has the attribute. ‘Is_lozalizable’ 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"
}