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.

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.