Catalog Product Attribute API¶
Introduction¶
The Catalog Product Attribute API allows you to manage product attributes, attribute sets, attribute options, product types, media, and tier prices in your OpenMage store.
Catalog Product Attribute¶
items¶
Retrieve attributes from specified attribute set.
Method Name: catalog_product_attribute.items
Parameters:
setId
(int, required) - Attribute set ID
Return:
- (array) - Array of attributes with the following structure:
attribute_id
(int) - Attribute IDcode
(string) - Attribute codetype
(string) - Attribute typerequired
(boolean) - Whether the attribute is requiredscope
(string) - Attribute scope (global, website, store)
Example Request:
{
"jsonrpc": "2.0",
"method": "call",
"params": [
"session_id",
"catalog_product_attribute.items",
4
],
"id": 1
}
Example Response:
{
"jsonrpc": "2.0",
"result": [
{
"attribute_id": 73,
"code": "name",
"type": "text",
"required": true,
"scope": "store"
},
{
"attribute_id": 74,
"code": "description",
"type": "textarea",
"required": false,
"scope": "store"
}
],
"id": 1
}
options¶
Retrieve attribute options.
Method Name: catalog_product_attribute.options
Parameters:
attributeId
(int, required) - Attribute IDstore
(string|int, optional) - Store ID or code
Return:
- (array) - Array of attribute options with the following structure:
value
(string) - Option valuelabel
(string) - Option label
Example Request:
{
"jsonrpc": "2.0",
"method": "call",
"params": [
"session_id",
"catalog_product_attribute.options",
[142, "default"]
],
"id": 1
}
Example Response:
{
"jsonrpc": "2.0",
"result": [
{
"value": "",
"label": ""
},
{
"value": "1",
"label": "Option 1"
},
{
"value": "2",
"label": "Option 2"
}
],
"id": 1
}
Possible Errors:
not_exists
- Attribute does not exist
types¶
Retrieve list of possible attribute types.
Method Name: catalog_product_attribute.types
Parameters: None
Return:
- (array) - Array of attribute types with the following structure:
value
(string) - Type valuelabel
(string) - Type label
Example Request:
{
"jsonrpc": "2.0",
"method": "call",
"params": [
"session_id",
"catalog_product_attribute.types",
[]
],
"id": 1
}
Example Response:
{
"jsonrpc": "2.0",
"result": [
{
"value": "text",
"label": "Text Field"
},
{
"value": "textarea",
"label": "Text Area"
},
{
"value": "select",
"label": "Dropdown"
},
{
"value": "multiselect",
"label": "Multiple Select"
},
{
"value": "boolean",
"label": "Yes/No"
},
{
"value": "date",
"label": "Date"
},
{
"value": "price",
"label": "Price"
}
],
"id": 1
}
create¶
Create new product attribute.
Method Name: catalog_product_attribute.create
Parameters:
data
(array, required) - Attribute data:attribute_code
(string, required) - Attribute codefrontend_input
(string, required) - Frontend input typescope
(string, required) - Attribute scope (global, website, store)default_value
(string, optional) - Default valueis_unique
(boolean, optional) - Whether the attribute is uniqueis_required
(boolean, optional) - Whether the attribute is requiredapply_to
(array, optional) - Product types to apply tois_configurable
(boolean, optional) - Whether the attribute is configurableis_searchable
(boolean, optional) - Whether the attribute is searchableis_visible_in_advanced_search
(boolean, optional) - Whether the attribute is visible in advanced searchis_comparable
(boolean, optional) - Whether the attribute is comparableis_used_for_promo_rules
(boolean, optional) - Whether the attribute is used for promo rulesis_visible_on_front
(boolean, optional) - Whether the attribute is visible on frontused_in_product_listing
(boolean, optional) - Whether the attribute is used in product listingfrontend_label
(array, required) - Array of frontend labels with the following structure:store_id
(int) - Store IDlabel
(string) - Label
additional_fields
(array, optional) - Additional fields based on frontend input type
Return:
- (int) - ID of the created attribute
Example Request:
{
"jsonrpc": "2.0",
"method": "call",
"params": [
"session_id",
"catalog_product_attribute.create",
{
"attribute_code": "custom_attribute",
"frontend_input": "select",
"scope": "global",
"is_required": false,
"frontend_label": [
{
"store_id": 0,
"label": "Custom Attribute"
}
],
"is_searchable": true,
"is_visible_in_advanced_search": true,
"is_comparable": true,
"is_visible_on_front": true
}
],
"id": 1
}
Example Response:
Possible Errors:
invalid_parameters
- Invalid parameters providedinvalid_code
- Invalid attribute codeinvalid_frontend_input
- Invalid frontend input typeunable_to_save
- Unable to save attribute
update¶
Update product attribute.
Method Name: catalog_product_attribute.update
Parameters:
attribute
(int|string, required) - Attribute ID or codedata
(array, required) - Attribute data to update (same structure as in create method)
Return:
- (boolean) - True on success
Example Request:
{
"jsonrpc": "2.0",
"method": "call",
"params": [
"session_id",
"catalog_product_attribute.update",
[
"custom_attribute",
{
"frontend_label": [
{
"store_id": 0,
"label": "Updated Custom Attribute"
}
],
"is_searchable": false
}
]
],
"id": 1
}
Example Response:
Possible Errors:
can_not_edit
- Attribute cannot be editedunable_to_save
- Unable to save attribute
remove¶
Remove attribute.
Method Name: catalog_product_attribute.remove
Parameters:
attribute
(int|string, required) - Attribute ID or code
Return:
- (boolean) - True on success
Example Request:
{
"jsonrpc": "2.0",
"method": "call",
"params": [
"session_id",
"catalog_product_attribute.remove",
"custom_attribute"
],
"id": 1
}
Example Response:
Possible Errors:
can_not_delete
- Attribute cannot be deleted
info¶
Get full information about attribute with list of options.
Method Name: catalog_product_attribute.info
Parameters:
attribute
(int|string, required) - Attribute ID or code
Return:
- (array) - Attribute data with the following structure:
attribute_id
(int) - Attribute IDattribute_code
(string) - Attribute codefrontend_input
(string) - Frontend input typedefault_value
(string) - Default valueis_unique
(boolean) - Whether the attribute is uniqueis_required
(boolean) - Whether the attribute is requiredapply_to
(array) - Product types to apply tois_configurable
(boolean) - Whether the attribute is configurableis_searchable
(boolean) - Whether the attribute is searchableis_visible_in_advanced_search
(boolean) - Whether the attribute is visible in advanced searchis_comparable
(boolean) - Whether the attribute is comparableis_used_for_promo_rules
(boolean) - Whether the attribute is used for promo rulesis_visible_on_front
(boolean) - Whether the attribute is visible on frontused_in_product_listing
(boolean) - Whether the attribute is used in product listingfrontend_label
(array) - Array of frontend labelsscope
(string) - Attribute scope (global, website, store)additional_fields
(array) - Additional fields based on frontend input typeoptions
(array) - Array of attribute options
Example Request:
{
"jsonrpc": "2.0",
"method": "call",
"params": [
"session_id",
"catalog_product_attribute.info",
"color"
],
"id": 1
}
Example Response:
{
"jsonrpc": "2.0",
"result": {
"attribute_id": 143,
"attribute_code": "color",
"frontend_input": "select",
"default_value": "",
"is_unique": false,
"is_required": false,
"apply_to": [],
"is_configurable": true,
"is_searchable": true,
"is_visible_in_advanced_search": true,
"is_comparable": true,
"is_used_for_promo_rules": false,
"is_visible_on_front": true,
"used_in_product_listing": false,
"frontend_label": [
{
"store_id": 0,
"label": "Color"
}
],
"scope": "global",
"additional_fields": {
"is_filterable": 1,
"is_filterable_in_search": 1,
"position": 0,
"used_for_sort_by": 0
},
"options": [
{
"value": "1",
"label": "Red"
},
{
"value": "2",
"label": "Blue"
},
{
"value": "3",
"label": "Green"
}
]
},
"id": 1
}
addOption
¶
Add option to select or multi-select attribute.
Method Name: catalog_product_attribute.addOption
Parameters:
attribute
(int|string, required) - Attribute ID or codedata
(array, required) - Option data:label
(array, required) - Array of option labels with the following structure:store_id
(int|array) - Store ID or array of store IDsvalue
(string) - Option label
order
(int, optional) - Option orderis_default
(boolean, optional) - Whether the option is default
Return:
- (boolean) - True on success
Example Request:
{
"jsonrpc": "2.0",
"method": "call",
"params": [
"session_id",
"catalog_product_attribute.addOption",
[
"color",
{
"label": [
{
"store_id": 0,
"value": "Yellow"
}
],
"order": 4,
"is_default": false
}
]
],
"id": 1
}
Example Response:
Possible Errors:
invalid_frontend_input
- Invalid frontend input typeunable_to_add_option
- Unable to add option
removeOption
¶
Remove option from select or multi-select attribute.
Method Name: catalog_product_attribute.removeOption
Parameters:
attribute
(int|string, required) - Attribute ID or codeoptionId
(int, required) - Option ID to remove
Return:
- (boolean) - True on success
Example Request:
{
"jsonrpc": "2.0",
"method": "call",
"params": [
"session_id",
"catalog_product_attribute.removeOption",
["color", 4]
],
"id": 1
}
Example Response:
Possible Errors:
invalid_frontend_input
- Invalid frontend input typeunable_to_remove_option
- Unable to remove option
Catalog Product Attribute Set¶
items¶
Retrieve attribute set list.
Method Name: catalog_product_attribute_set.items
Parameters: None
Return:
- (array) - Array of attribute sets with the following structure:
set_id
(int) - Attribute set IDname
(string) - Attribute set name
Example Request:
{
"jsonrpc": "2.0",
"method": "call",
"params": [
"session_id",
"catalog_product_attribute_set.items",
[]
],
"id": 1
}
Example Response:
{
"jsonrpc": "2.0",
"result": [
{
"set_id": 4,
"name": "Default"
},
{
"set_id": 5,
"name": "Custom"
}
],
"id": 1
}
create¶
Create new attribute set based on another set.
Method Name: catalog_product_attribute_set.create
Parameters:
attributeSetName
(string, required) - Attribute set nameskeletonSetId
(int, required) - Skeleton attribute set ID
Return:
- (int) - ID of the created attribute set
Example Request:
{
"jsonrpc": "2.0",
"method": "call",
"params": [
"session_id",
"catalog_product_attribute_set.create",
["New Attribute Set", 4]
],
"id": 1
}
Example Response:
Possible Errors:
invalid_skeleton_set_id
- Invalid skeleton attribute set IDinvalid_data
- Invalid data providedcreate_attribute_set_error
- Error creating attribute set
remove¶
Remove attribute set.
Method Name: catalog_product_attribute_set.remove
Parameters:
attributeSetId
(int, required) - Attribute set IDforceProductsRemove
(boolean, optional) - Force removal of products with this attribute set
Return:
- (boolean) - True on success
Example Request:
{
"jsonrpc": "2.0",
"method": "call",
"params": [
"session_id",
"catalog_product_attribute_set.remove",
[6, false]
],
"id": 1
}
Example Response:
Possible Errors:
invalid_attribute_set_id
- Invalid attribute set IDattribute_set_has_related_products
- Attribute set has related productsremove_attribute_set_error
- Error removing attribute set
attributeAdd
¶
Add attribute to attribute set.
Method Name: catalog_product_attribute_set.attributeAdd
Parameters:
attributeId
(int, required) - Attribute IDattributeSetId
(int, required) - Attribute set IDattributeGroupId
(int, optional) - Attribute group IDsortOrder
(int, optional) - Sort order
Return:
- (boolean) - True on success
Example Request:
{
"jsonrpc": "2.0",
"method": "call",
"params": [
"session_id",
"catalog_product_attribute_set.attributeAdd",
[145, 5, null, 0]
],
"id": 1
}
Example Response:
Possible Errors:
invalid_attribute_id
- Invalid attribute IDinvalid_attribute_set_id
- Invalid attribute set IDinvalid_attribute_group_id
- Invalid attribute group IDattribute_is_already_in_set
- Attribute is already in setadd_attribute_error
- Error adding attribute
attributeRemove
¶
Remove attribute from attribute set.
Method Name: catalog_product_attribute_set.attributeRemove
Parameters:
attributeId
(int, required) - Attribute IDattributeSetId
(int, required) - Attribute set ID
Return:
- (boolean) - True on success
Example Request:
{
"jsonrpc": "2.0",
"method": "call",
"params": [
"session_id",
"catalog_product_attribute_set.attributeRemove",
[145, 5]
],
"id": 1
}
Example Response:
Possible Errors:
invalid_attribute_id
- Invalid attribute IDinvalid_attribute_set_id
- Invalid attribute set IDattribute_is_not_in_set
- Attribute is not in setremove_attribute_error
- Error removing attribute
groupAdd
¶
Create group within existing attribute set.
Method Name: catalog_product_attribute_set.groupAdd
Parameters:
attributeSetId
(int, required) - Attribute set IDgroupName
(string, required) - Group name
Return:
- (int) - ID of the created group
Example Request:
{
"jsonrpc": "2.0",
"method": "call",
"params": [
"session_id",
"catalog_product_attribute_set.groupAdd",
[5, "New Group"]
],
"id": 1
}
Example Response:
Possible Errors:
group_already_exists
- Group already existsgroup_add_error
- Error adding group
groupRename
¶
Rename existing group.
Method Name: catalog_product_attribute_set.groupRename
Parameters:
groupId
(int, required) - Group IDgroupName
(string, required) - New group name
Return:
- (boolean) - True on success
Example Request:
{
"jsonrpc": "2.0",
"method": "call",
"params": [
"session_id",
"catalog_product_attribute_set.groupRename",
[15, "Renamed Group"]
],
"id": 1
}
Example Response:
Possible Errors:
invalid_attribute_group_id
- Invalid attribute group IDgroup_rename_error
- Error renaming group
groupRemove
¶
Remove group from existing attribute set.
Method Name: catalog_product_attribute_set.groupRemove
Parameters:
attributeGroupId
(int, required) - Attribute group ID
Return:
- (boolean) - True on success
Example Request:
{
"jsonrpc": "2.0",
"method": "call",
"params": [
"session_id",
"catalog_product_attribute_set.groupRemove",
15
],
"id": 1
}
Example Response:
Possible Errors:
invalid_attribute_group_id
- Invalid attribute group IDgroup_has_configurable_attributes
- Group has configurable attributesgroup_has_system_attributes
- Group has system attributesgroup_remove_error
- Error removing group
Catalog Product Type¶
items¶
Retrieve product type list.
Method Name: catalog_product_type.items
Parameters: None
Return:
- (array) - Array of product types with the following structure:
type
(string) - Product type codelabel
(string) - Product type label
Example Request:
{
"jsonrpc": "2.0",
"method": "call",
"params": [
"session_id",
"catalog_product_type.items",
[]
],
"id": 1
}
Example Response:
{
"jsonrpc": "2.0",
"result": [
{
"type": "simple",
"label": "Simple Product"
},
{
"type": "configurable",
"label": "Configurable Product"
},
{
"type": "grouped",
"label": "Grouped Product"
},
{
"type": "virtual",
"label": "Virtual Product"
},
{
"type": "bundle",
"label": "Bundle Product"
},
{
"type": "downloadable",
"label": "Downloadable Product"
}
],
"id": 1
}
Catalog Product Attribute Media¶
items¶
Retrieve images for product.
Method Name: catalog_product_attribute_media.items
Parameters:
productId
(int|string, required) - Product ID or SKUstore
(string|int, optional) - Store ID or codeidentifierType
(string, optional) - Type of product identifier (‘sku’ or null for ID)
Return:
- (array) - Array of product images with the following structure:
file
(string) - Image file pathlabel
(string) - Image labelposition
(int) - Image positionexclude
(boolean) - Whether the image is excludedurl
(string) - Image URLtypes
(array) - Array of image types (image, small_image, thumbnail)
Example Request:
{
"jsonrpc": "2.0",
"method": "call",
"params": [
"session_id",
"catalog_product_attribute_media.items",
["product1", "default", "sku"]
],
"id": 1
}
Example Response:
{
"jsonrpc": "2.0",
"result": [
{
"file": "/p/r/product1.jpg",
"label": "Product 1",
"position": 1,
"exclude": false,
"url": "http://example.com/media/catalog/product/p/r/product1.jpg",
"types": ["image", "small_image", "thumbnail"]
},
{
"file": "/p/r/product1_2.jpg",
"label": "Product 1 - 2",
"position": 2,
"exclude": false,
"url": "http://example.com/media/catalog/product/p/r/product1_2.jpg",
"types": []
}
],
"id": 1
}
Possible Errors:
product_not_exists
- Product does not exist
info¶
Retrieve image data.
Method Name: catalog_product_attribute_media.info
Parameters:
productId
(int|string, required) - Product ID or SKUfile
(string, required) - Image file pathstore
(string|int, optional) - Store ID or codeidentifierType
(string, optional) - Type of product identifier (‘sku’ or null for ID)
Return:
- (array) - Image data with the same structure as in items method
Example Request:
{
"jsonrpc": "2.0",
"method": "call",
"params": [
"session_id",
"catalog_product_attribute_media.info",
["product1", "/p/r/product1.jpg", "default", "sku"]
],
"id": 1
}
Example Response:
{
"jsonrpc": "2.0",
"result": {
"file": "/p/r/product1.jpg",
"label": "Product 1",
"position": 1,
"exclude": false,
"url": "http://example.com/media/catalog/product/p/r/product1.jpg",
"types": ["image", "small_image", "thumbnail"]
},
"id": 1
}
Possible Errors:
product_not_exists
- Product does not existnot_exists
- Image does not exist
create¶
Create new image for product and return image filename.
Method Name: catalog_product_attribute_media.create
Parameters:
productId
(int|string, required) - Product ID or SKUdata
(array, required) - Image data:file
(array, required) - Image file data:content
(string, required) - Base64-encoded image contentmime
(string, required) - Image MIME typename
(string, optional) - Image name
label
(string, optional) - Image labelposition
(int, optional) - Image positionexclude
(boolean, optional) - Whether the image is excludedtypes
(array, optional) - Array of image types (image, small_image, thumbnail)store
(string|int, optional) - Store ID or codeidentifierType
(string, optional) - Type of product identifier (‘sku’ or null for ID)
Return:
- (string) - Image file path
Example Request:
{
"jsonrpc": "2.0",
"method": "call",
"params": [
"session_id",
"catalog_product_attribute_media.create",
[
"product1",
{
"file": {
"content": "base64-encoded-image-content",
"mime": "image/jpeg",
"name": "product1_3.jpg"
},
"label": "Product 1 - 3",
"position": 3,
"types": ["image"]
},
"default",
"sku"
]
],
"id": 1
}
Example Response:
Possible Errors:
product_not_exists
- Product does not existdata_invalid
- Invalid data providednot_created
- Image could not be created
update¶
Update image data.
Method Name: catalog_product_attribute_media.update
Parameters:
productId
(int|string, required) - Product ID or SKUfile
(string, required) - Image file pathdata
(array, required) - Image data to update (same structure as in create method)store
(string|int, optional) - Store ID or codeidentifierType
(string, optional) - Type of product identifier (‘sku’ or null for ID)
Return:
- (boolean) - True on success
Example Request:
{
"jsonrpc": "2.0",
"method": "call",
"params": [
"session_id",
"catalog_product_attribute_media.update",
[
"product1",
"/p/r/product1_3.jpg",
{
"label": "Updated Product 1 - 3",
"position": 4,
"types": ["small_image"]
},
"default",
"sku"
]
],
"id": 1
}
Example Response:
Possible Errors:
product_not_exists
- Product does not existnot_exists
- Image does not existdata_invalid
- Invalid data providednot_updated
- Image could not be updated
remove¶
Remove image from product.
Method Name: catalog_product_attribute_media.remove
Parameters:
productId
(int|string, required) - Product ID or SKUfile
(string, required) - Image file pathidentifierType
(string, optional) - Type of product identifier (‘sku’ or null for ID)
Return:
- (boolean) - True on success
Example Request:
{
"jsonrpc": "2.0",
"method": "call",
"params": [
"session_id",
"catalog_product_attribute_media.remove",
["product1", "/p/r/product1_3.jpg", "sku"]
],
"id": 1
}
Example Response:
Possible Errors:
product_not_exists
- Product does not existnot_exists
- Image does not existnot_removed
- Image could not be removed
types¶
Retrieve image types (image, small_image, thumbnail, etc…).
Method Name: catalog_product_attribute_media.types
Parameters:
setId
(int, required) - Attribute set ID
Return:
- (array) - Array of image types with the following structure:
code
(string) - Image type codescope
(string) - Image type scope (global, website, store)
Example Request:
{
"jsonrpc": "2.0",
"method": "call",
"params": [
"session_id",
"catalog_product_attribute_media.types",
4
],
"id": 1
}
Example Response:
{
"jsonrpc": "2.0",
"result": [
{
"code": "image",
"scope": "store"
},
{
"code": "small_image",
"scope": "store"
},
{
"code": "thumbnail",
"scope": "store"
}
],
"id": 1
}
Catalog Product Attribute Tier Price¶
info¶
Retrieve tier prices for a product.
Method Name: catalog_product_attribute_tier_price.info
Parameters:
productId
(int|string, required) - Product ID or SKUidentifierType
(string, optional) - Type of product identifier (‘sku’ or null for ID)
Return:
- (array) - Array of tier prices with the following structure:
customer_group_id
(string) - Customer group ID or ‘all’ for all groupswebsite
(string) - Website code or ‘all’ for all websitesqty
(float) - Quantityprice
(float) - Price
Example Request:
{
"jsonrpc": "2.0",
"method": "call",
"params": [
"session_id",
"catalog_product_attribute_tier_price.info",
["product1", "sku"]
],
"id": 1
}
Example Response:
{
"jsonrpc": "2.0",
"result": [
{
"customer_group_id": "all",
"website": "all",
"qty": 2,
"price": 19.99
},
{
"customer_group_id": "1",
"website": "base",
"qty": 5,
"price": 17.99
}
],
"id": 1
}
Possible Errors:
product_not_exists
- Product does not exist
update¶
Update tier prices of product.
Method Name: catalog_product_attribute_tier_price.update
Parameters:
productId
(int|string, required) - Product ID or SKUtierPrices
(array, required) - Array of tier prices with the following structure:customer_group_id
(string, optional) - Customer group ID or ‘all’ for all groups (default: ‘all’)website
(string, optional) - Website code or ‘all’ for all websites (default: ‘all’)qty
(float, required) - Quantityprice
(float, required) - PriceidentifierType
(string, optional) - Type of product identifier (‘sku’ or null for ID)
Return:
- (boolean) - True on success
Example Request:
{
"jsonrpc": "2.0",
"method": "call",
"params": [
"session_id",
"catalog_product_attribute_tier_price.update",
[
"product1",
[
{
"customer_group_id": "all",
"website": "all",
"qty": 2,
"price": 19.99
},
{
"customer_group_id": "1",
"website": "base",
"qty": 5,
"price": 17.99
}
],
"sku"
]
],
"id": 1
}
Example Response:
Possible Errors:
product_not_exists
- Product does not existdata_invalid
- Invalid data providednot_updated
- Tier prices could not be updated