Plugins
In the Commerce system, plugins are used to load additional data on the product listing page. Currently, there is only one type of plugin available. New plugin definitions are requested and developed by the Commerce team based on requirements.
Available Plugin:
products.listable_product_variants
The only plugin currently available in the system allows additional data, defined for the plugin, to be added to the existing product data on the listing page. Once a plugin is defined, existing products must be reindexed to reflect its effects.
The next section details how to list and create plugins using the Commerce API.
Listable Product Variants Plugin
The products.listable_product_variants plugin is used to add extra data to the extra_data field within a product on the listing page.
Default extra_data Field Without Plugin:
If the plugin is not available or is inactive, the extra_data field of a product on the listing page appears as follows:
"extra_data": {
"variants": []
}
Modified extra_data Field with Plugin:
When the plugin is configured with the following settings:
"config": {
"attribute_keys": [
"size",
"color"
],
"product_field_names": [
"pk",
"price",
"absolute_url",
"productimage_set",
"attributes"
],
"attribute_set_attributes": {}
}
The extra_data field on the listing page is modified as follows:
"extra_data": {
"variants": [
{
"options": [{
"label": "XS",
"product": {
"pk": 114768,
"sku": "5797434",
"price": "1599",
"attributes": {},
"absolute_url": "/product/114768/",
"productimage_set": []
},
"in_stock": true,
"is_selectable": true
}],
"attribute_key": "color"
},
{
"options": [
{},
{},
{},
{}
],
"attribute_key": "size"
}
]
}
The modified structure results from defining attribute_keys with values like color and size. This allows variants of the product based on these attribute values to be listed within extra_data.
Additionally, the product_field_names setting defines which fields of the variant products should be included in the response. In the example above, the fields pk, price, absolute_url, productimage_set, and attributes are specified, ensuring that these details are included when displaying variant products.
Note: The attributes specified in attribute_keys must be variant attributes. That is, they should correspond to attributes that define different variations of a product (e.g., color, size) rather than general product attributes.
Plugin API Endpoints
GET List Plugins
This endpoint retrieves the plugin settings stored in the database.
Path: /api/v1/plugins/
Example Request
curl --location '{commerce_url}/api/v1/plugins/'
Example Response
{
"count": 1,
"next": null,
"previous": null,
"results": [
{
"pk": 2,
"key": "products.listable_product_variants",
"name": "Listable Product Variants",
"description": "...",
"is_active": false,
"config": {
"attribute_keys": [],
"product_field_names": ["attributes"],
"attribute_set_attributes": {}
},
"default_config": {
"attribute_keys": [],
"product_field_names": ["attributes", "pk", "..."],
"attribute_set_attributes": {}
}
}
]
}
Response Parameters
| Key | Description |
|---|---|
pk | Contains the ID of the plugin. |
key | Stores the KEY attribute value of the plugin class. |
name | Stores the NAME attribute value of the plugin class. |
description | Stores the DESCRIPTION attribute value of the plugin class. |
config | Contains the CONFIG attribute value of the plugin. |
default_config | Contains the DEFAULT CONFIG attribute value of the plugin. |
is_active | Indicates whether the plugin is active. |
GET List All Available Plugins
This endpoint retrieves all plugin classes registered in the Plugin Registry.
Path: /api/v1/plugins/all/
Example Request
curl --location '{commerce_url}/api/v1/plugins/all/'
Example Response
[
{
"key": "products.listable_product_variants",
"name": "Listable Product Variants",
"description": "...",
"config": {
"attribute_keys": [],
"product_field_names": [
"pk",
"price",
"absolute_url",
"productimage_set",
"attributes"
],
"attribute_set_attributes": {}
},
"is_active": false
}
]
Response Parameters
| Key | Description |
|---|---|
key | Stores the KEY attribute value of the plugin class. |
name | Stores the NAME attribute value of the plugin class. |
description | Stores the DESCRIPTION attribute value of the plugin class. |
config | Contains the CONFIG attribute value of the plugin. |
is_active | Indicates whether the plugin is active. |
POST Create a Plugin
This endpoint is used to add settings and activate a plugin. Only one record can be created for each plugin key, and duplicate records are not allowed. If the provided key does not exist in the Plugin Registry, the API returns an error: Plugin with this key does not exist.
The config key in the request body must contain a dictionary formatted according to the config_serializer defined in the plugin class.
Path: /api/v1/plugins/
Request Body Parameters
| Key | Description |
|---|---|
key | Must contain the KEY attribute value of the plugin class. |
config | Must contain a valid configuration according to the serializer. |
is_active | Indicates whether the plugin is active. |
Example Request
curl --location '{commerce_url}/api/v1/plugins/' \
--header 'Content-Type: application/json' \
--data '{
"key": "products.listable_product_variants",
"config": {
"product_field_names": [
"pk",
"price",
"retail_product",
"attributes"
],
"attribute_keys": [],
"attribute_set_attributes": {}
},
"is_active": false
}'
Example Response
{
"pk": 2,
"key": "products.listable_product_variants",
"name": "Listable Product Variants",
"description": "...",
"is_active": false,
"config": {
"attribute_keys": [],
"product_field_names": [
"pk",
"price",
"retail_product",
"attributes"
],
"attribute_set_attributes": {}
},
"default_config": {
"attribute_keys": [],
"product_field_names": [
"attributes", "pk", "..."
],
"attribute_set_attributes": {}
}
}
Response Parameters
| Key | Description |
|---|---|
pk | Contains the ID of the plugin. |
key | Stores the KEY attribute value of the plugin class. |
name | Stores the NAME attribute value of the plugin class. |
description | Stores the DESCRIPTION attribute value of the plugin class. |
config | Contains the CONFIG attribute value of the plugin. |
default_config | Contains the DEFAULT CONFIG attribute value of the plugin. |
is_active | Indicates whether the plugin is active. |
PUT Update a Plugin
This endpoint updates the settings and activation status of an existing plugin. If a plugin has not been added previously, it must be created first.
The config key in the request body must contain a dictionary formatted according to the config_serializer defined in the plugin class.
Path: /api/v1/plugins/
Request Body Parameters
| Key | Description |
|---|---|
key | Must contain the KEY attribute value of the plugin class. |
config | Must contain a valid configuration according to the serializer. |
is_active | Indicates whether the plugin is active. |
Example Request
curl --location --request PUT '{commerce_url}/api/v1/plugins/3/' \
--data '{
"key": "products.listable_product_variants",
"config": {
"product_field_names": ["pk", "attributes"],
"attribute_keys": [],
"attribute_set_attributes": {}
},
"is_active": false // Deactivating the plugin
}'
Example Response
{
"pk": 3,
"key": "products.listable_product_variants",
"name": "Listable Product Variants",
"description": "...",
"is_active": false,
"config": {
"attribute_keys": [],
"product_field_names": [
"pk","attributes"
],
"attribute_set_attributes": {}
},
"default_config": {
"attribute_keys": [],
"product_field_names": [
"pk",
"price",
"retail_product",
"absolute_url",
"productimage_set",
"attributes"
],
"attribute_set_attributes": {}
}
}
Response Parameters
| Key | Description |
|---|---|
pk | Contains the ID of the plugin. |
key | Stores the KEY attribute value of the plugin class. |
name | Stores the NAME attribute value of the plugin class. |
description | Stores the DESCRIPTION attribute value of the plugin class. |
config | Contains the CONFIG attribute value of the plugin. |
default_config | Contains the DEFAULT CONFIG attribute value of the plugin. |
is_active | Indicates whether the plugin is active. |