Developer documentation

Dear developer,

Joomla! is not only the best CMS because of its core team; Joomla! is empowered by all the third-party extensions, professional or not, which add so many functionalities to any website.
We decided to open HikaShop to any addition using a the powerful Joomla Plugin system.

HikaShop Developer Documentation

HikaShop provides a powerful plugin system based on the standard Joomla plugin system.

HikaShop events are triggered when certain actions are performed (order creation, product deletion, etc.). To use these events, you need to create a Joomla plugin of the group "hikashop", "hikashoppayment" or "hikashopshipping".

This document explains the available events, the HikaShop API, and providing code samples for common tasks.

Summary

The first thing you have to do is to create a standard Joomla plugin. The group will be "hikashop" unless you create a payment or shipping plugin, in which case it will be "hikashoppayment" or "hikashopshipping" respectively. Then, you can install it on Joomla.

We recommend that you first learn how to create Joomla plugins before starting to create HikaShop plugins since HikaShop plugins are actually Joomla plugins: Joomla Plugin Development Documentation

How to create a HikaShop plugin

When you create a plugin for HikaShop, while you can extend JPlugin (or \Joomla\CMS\Plugin\CMSPlugin for modern Joomla versions), we highly recommend extending the hikashopPlugin class.

The hikashopPlugin class provides a compatibility bridge for Joomla 3, 4, 5, and 6, and includes several useful helper methods:

  • showPage($name): Renders a specific plugin view file, supporting template overrides (e.g., $this->showPage('thanks') will look for yourplugin_thanks.php).
  • listPlugins($name, &$values): Helps list all instances of a plugin type.

Input Handling with hikaInput

To ensure your plugin works across all Joomla versions (where JRequest is deprecated and $app->input varies), we recommend using the hikaInput class provided by HikaShop:

$input = hikaInput::get();
$myValue = $input->get('my_param', 'default_value', 'string');

Multiple instances: You can allow a plugin to have several instances (each with its own configuration) by setting public $multiple = true;. You then define the configuration fields in the public $pluginConfig array. For each field, you specify a label, a type (e.g., 'boolean', 'category', 'list', 'text'), and optional parameters or default values. This is useful for plugins that need different settings for different scenarios, like the Shop Close Hours plugin (plg_hikashop_shopclosehours). The hikashopPlugin class automatically handles the display and saving of these parameters for each instance.

In your plugin, simply create functions matches the names of the events you want to handle.

Here is an example using two events: onBeforeOrderCreate and onAfterOrderCreate. By extending hikashopPlugin, the database object $this->db is automatically initialized.

class plgHikashopName extends hikashopPlugin {
	function __construct(&$subject, $config){
		parent::__construct($subject, $config);
	}

	function onBeforeOrderCreate(&$order, &$do){
		/* code to be executed before the order is created */
	}

	function onAfterOrderCreate(&$order){
		/* code to be executed after the order is created */
	}
}

All events have different parameters. You can find the list of events below. Marc Studer also developed a helpful plugin to see which HikaShop event is triggered on each page: hikashop_dump_events on GitHub.

We recommend studying the HikaShop Email history plugin (/plugins/hikashop/email_history/), as it is one of the simplest examples for understanding the HikaShop plugin structure. Its goal is to store all emails sent to customers in a database table and display them in a list in the admin panel.

How to create a HikaShop Payment plugin

First, we invite you to read the information on the Payment API section.

Then, you can go to the Example Payment Plugin GitHub and look at the files. Each line of the plugin is documented, explaining how a payment plugin should be structured. It's an excellent base if you are a developer but have never integrated a payment gateway before.

You can also study the source code of payment plugins included in HikaShop by exploring the /plugins/hikashoppayment/ folder of your installation.

How to create a HikaShop Shipping plugin

First, we invite you to read the information on the Shipping API section.

Then, you can go to the Example Shipping Plugin GitHub and look at the files. Each line of the plugin is documented, explaining how a shipping plugin should be structured. It covers advanced topics like multiple packages, custom HTML selection, and automated carrier export.

You can also study the source code of shipping plugins included in HikaShop by exploring the /plugins/hikashopshipping/ folder of your installation.

Order API

Available events for the Order API:

Functions are called if they exist; you don't have to define them all.
These functions are triggered by HikaShop when an order is saved or deleted. The cron task is only available on commercial versions of HikaShop.

onBeforeOrderCreate(&$order, &$do)

Triggered before a new order is saved. The $order object contains the full order data. Setting $do to false cancels the order creation.

  • &$order: The order object.
  • &$do: A boolean. Set it to false to cancel the order creation.

onBeforeOrderUpdate(&$order, &$do)

Triggered before an existing order is updated. The $order object contains the updated information. Setting $do to false cancels the update.

  • &$order: The order object.
  • &$do: A boolean. Set it to false to cancel the update.

onBeforeOrderDelete(&$elements, &$do)

Triggered before one or several orders are deleted. $elements is an array of order IDs. Setting $do to false cancels the deletion.

  • &$elements: An array of order IDs to be deleted.
  • &$do: A boolean. Set it to false to cancel the deletion.

onAfterOrderCreate(&$order, &$send_email)

Triggered after an order is successfully created. The $order object contains the full order data. Setting $send_email to false prevents the customer notification email.

  • &$order: The order object.
  • &$send_email: A boolean. Set it to false to prevent the customer notification email.

onAfterOrderConfirm(&$order, &$methods, $method_id)

This method is called at the end of the checkout when an order is created. Note: This is specifically for the payment plugin associated with the selected payment method. It is often used to redirect the user to a payment gateway.

For payment notifications (webhooks), the notification URL should target: index.php?option=com_hikashop&ctrl=checkout&task=notify&notif_payment=PAYMENT_PLUGIN_NAME. This triggers the onPaymentNotification method in your plugin.

We recommend including the lang parameter in the notification URL to ensure emails sent during notification are in the correct language.

onAfterOrderUpdate(&$order, &$send_email)

Triggered after an order is updated. The $order object contains the updated information. Setting $send_email to false prevents the status change notification email.

  • &$order: The order object.
  • &$send_email: A boolean. Set it to false to prevent the status change notification email.

onAfterOrderDelete($elements)

Triggered after one or several orders are deleted. $elements is either a single ID or an array of order IDs.

  • $elements: A single order ID or an array of order IDs.

onAfterInvoiceCreate(&$order)

Triggered after an invoice is generated for an order. This usually happens when the order status changes to "confirmed" or "shipped".

onAfterLoadFullOrder(&$order)

Triggered after an order is fully loaded from the database, including its products, addresses, and history. $order is the complete order object. This is a good place to add custom fields or other data to the order object, or to modify the order object before it is used.

  • &$order: The complete order object.

onBeforeOrderProductsUpdate(&$order, &$do)

Triggered before the products of an order are updated in the database (e.g., when editing an order in the backend).

  • &$order: The order object containing the modified product array.
  • &$do: A boolean. Set it to false to cancel the products update.

onHistoryDisplay(&$history)

Triggered when the history of an order is displayed in the backend. You can use it to modify the $history object before display.

 

onBeforeOrderExport(&$rows, &$obj)

Triggered before orders are exported. $rows contains the array of order objects to be exported.

 

onBeforeOrderNumberGenerate(&$data, &$result)

Triggered during order creation to generate the order number. $data contains the order attributes. You can set a custom order number in $result to override the default HikaShop format.

 

onBeforeInvoiceNumberGenerate(&$data, &$result)

Triggered when an invoice number is generated. $data contains the order attributes. Set custom text in $result to override the default invoice number format.

onBeforeOrderPaymentCapture(&$order, $order_full_price, &$order_capture_price, &$do)

Triggered before a payment capture is processed (for payment methods supporting authorization/capture).

  • &$order: The order object.
  • $order_full_price: The total amount of the order.
  • &$order_capture_price: The amount to be captured. You can modify this value.
  • &$do: A boolean. Set it to false to cancel the capture.

 

onBeforeOrderListing($paramBase, &$extrafilters, &$pageInfo, &$filters, &$tables, &$searchMap, &$select)

Triggered before running the database query to load orders in the backend. You can modify the query (adding conditions, joins, etc.) or add custom filters to the listing.

To add a custom filter, register your plugin in the $extrafilters array and implement a displayFilter function.

class plgHikashopName extends JPlugin {
    function onBeforeOrderListing($paramBase, &$extrafilters, &$pageInfo, &$filters, &$tables, &$searchMap, &$select) {
        // Register for extra filter display
        $extrafilters['my_extra_filter'] = $this;
        
        $app = JFactory::getApplication();
        $pageInfo->filter->filter_order_published = $app->getUserStateFromRequest($paramBase.".filter_order_published", 'filter_order_published', 1, 'int');

        if(!empty($pageInfo->filter->filter_order_published)) {
            $filters[] = 'b.order_published = ' . (int)$pageInfo->filter->filter_order_published;
        }
    }

    function displayFilter($name, $info) {
        if($name == 'my_extra_filter') {
            $values = array(
                JHTML::_('select.option', '0', JText::_('HIKA_ALL')),
                JHTML::_('select.option', '1', JText::_('HIKA_PUBLISHED')),
                JHTML::_('select.option', '-1', JText::_('HIKA_UNPUBLISHED')),
            );
            return JHTML::_('select.genericlist', $values, 'filter_order_published', 'onchange="document.adminForm.submit();"', 'value', 'text', @$info->filter_order_published, 'order_published');
        }
    }
}

You can refer to the Orders Product Filter plugin for a complete example.

onBeforeCalculateProductPriceForQuantityInOrder(&$orderProduct)

Triggered during order creation before calculating the total price of a product in the order. $orderProduct contains the product details and its unit price.

  • &$orderProduct: The order product object.

onAfterCalculateProductPriceForQuantityInOrder(&$orderProduct)

Triggered after calculating the total price of a product in the order. You can use it to override the order_product_total_price and order_product_total_price_no_vat values.

  • &$orderProduct: The order product object.

 

Product API

This API allows you to perform actions when products are created, updated, deleted, or displayed.

Available events for the Product API:

onBeforeProductCreate(&$element, &$do)

Triggered before a product is created. $element contains the product data. Setting $do to false cancels the creation.

  • &$element: The product object to be created.
  • &$do: A boolean. Set it to false to cancel the product creation.

onAfterProductCreate(&$element)

Triggered after a product is successfully created. $element includes the new product_id.

  • &$element: The created product object.

onBeforeProductUpdate(&$element, &$do)

Triggered before a product is updated. $element contains the updated data. Setting $do to false cancels the update.

  • &$element: The product object to be updated.
  • &$do: A boolean. Set it to false to cancel the update.

onAfterProductUpdate(&$element)

Triggered after a product is successfully updated.

onBeforeProductDelete(&$ids, &$do)

Triggered before one or more products are deleted. $ids is an array of product IDs. Setting $do to false cancels the deletion.

  • &$ids: An array of product IDs to be deleted.
  • &$do: A boolean. Set it to false to cancel the deletion.

onAfterProductDelete(&$ids)

Triggered after one or more products are successfully deleted.

onBeforeProductListingLoad(&$filters, &$order, &$view, &$select, &$select2, &$a, &$b, &$on)

Triggered when products are loaded for a listing on the frontend. You can modify the query parts before it's executed.

  • &$filters: An array of WHERE clauses (strings).
  • &$order: The ORDER BY clause (string).
  • &$view: The current view object.
  • &$select: The main SELECT part (string).
  • &$select2: Additional SELECT parts (string).
  • &$a: The table alias for product_category (string).
  • &$b: The table alias for product (string).
  • &$on: The JOIN/ON clause (string).

You can also add a LEFT JOIN by appending it to the $on variable:

$on .= ' LEFT JOIN #__hikashop_price AS p ON b.product_id = p.price_product_id';
$order = ' p.price_value ASC';

 

onBeforeProductCopy(&$template, &$product, &$do)

Triggered before copying a product. You can update the $template or the $product values. Setting $do to false cancels the copy.

  • &$template: The product object used as a template for the copy.
  • &$product: The product object being copied.
  • &$do: A boolean. Set it to false to cancel the copy.

onAfterProductCopy(&$template, &$product)

Triggered after a product is successfully copied.

  • &$template: The template product object.
  • &$product: The newly created product object.

onBeforeProductExport(&$products, &$categories, &$obj)

Triggered before products are exported. $products and $categories contain the respective objects to be exported.

  • &$products: An array of product objects to be exported.
  • &$categories: An array of category objects associated with the products.
  • &$obj: The export object.

onBeforeLoadProductPrice(&$filters, &$rows, &$options)

Triggered before HikaShop loads prices for a list of products. You can modify the $filters or $options to change which prices are loaded.

  • &$filters: An array of WHERE clauses for the price query.
  • &$rows: The product rows for which prices are being loaded.
  • &$options: An array of options (zone_id, currency_id, etc).

onAfterLoadProductPrice(&$prices, &$rows, &$filters, &$options)

Triggered after HikaShop has loaded prices. $prices is an array of price objects.

  • &$prices: The loaded price objects.
  • &$rows: The product rows.
  • &$filters: The filters used for the query.
  • &$options: The options used for the query.

onBeforeLoadProductPriceDiscount(&$filters, $rows, $trigger_options)

Triggered before HikaShop loads discounts for a list of products.

  • &$filters: An array of WHERE clauses for the discount query.
  • $rows: The product rows.
  • $trigger_options: An array containing context (currency_id, user_id, zone_id, etc).

onAfterLoadProductPriceDiscount(&$discounts, &$rows, $filters, $trigger_options)

Triggered after HikaShop has loaded discounts.

  • &$discounts: The loaded discount objects.
  • &$rows: The product rows.
  • $filters: The filters used for the query.
  • $trigger_options: The context options.

onBeforeCalculateProductPriceForQuantity(&$product)

Triggered before calculating the unit price of a product based on the quantity in the cart. $product contains the product data and its available prices.

  • &$product: The product object containing its prices and the quantity in the cart.

onAfterCalculateProductPriceForQuantity(&$product)

Triggered after calculating the unit price. You can use it to override the final unit price chosen by HikaShop.

  • &$product: The product object with its calculated unit price.

 

Category API

This API allows you to perform actions when categories are created, updated, or deleted.

Available events for the Category API:

onBeforeCategoryCreate(&$element, &$do)

Triggered before a category is created. $element contains the category data. Setting $do to false cancels the creation.

  • &$element: The category object to be created.
  • &$do: A boolean. Set it to false to cancel the creation.

onAfterCategoryCreate(&$element)

Triggered after a category is successfully created. The $element object includes the new category_id.

  • &$element: The created category object.

onBeforeCategoryUpdate(&$element, &$do)

Triggered before a category is updated. $element contains the updated data. Setting $do to false cancels the update.

  • &$element: The category object with updated information.
  • &$do: A boolean. Set it to false to cancel the update.

onAfterCategoryUpdate(&$element)

Triggered after a category is successfully updated.

  • &$element: The updated category object.

onBeforeCategoryDelete(&$ids, &$do)

Triggered before one or more categories are deleted. $ids is an array of category IDs. Setting $do to false cancels the deletion.

  • &$ids: An array of category IDs to be deleted.
  • &$do: A boolean. Set it to false to cancel the deletion.

onAfterCategoryDelete(&$ids)

Triggered after one or more categories are successfully deleted.

  • &$ids: An array of deleted category IDs.

onBeforeCategoryListingLoad(&$filters, &$order, &$parentObject)

Triggered when categories are loaded for display on frontend and backend listings. The $filters variable is an array of conditions used to form the MySQL query. You can modify this array to change how categories are loaded by adding or removing conditions.

  • &$filters: An array of WHERE clauses (strings) for the category query.
  • &$order: The ORDER BY clause for the query.
  • &$parentObject: The parent object (usually a category) context for the listing.

Address API

This API allows you to perform actions when addresses are created, updated, or deleted.

Available events for the Address API:

onBeforeAddressCreate(&$element, &$do)

Triggered before an address is created. The $element object contains the address information. Setting $do to false cancels the creation.

  • &$element: The address object to be created.
  • &$do: A boolean. Set it to false to cancel the creation.

onBeforeAddressUpdate(&$element, &$do)

Triggered before an address is updated. The $element object contains the new address information. Setting $do to false cancels the update.

  • &$element: The address object with updated information.
  • &$do: A boolean. Set it to false to cancel the update.

onAfterAddressCreate(&$element)

Triggered after an address is successfully created. The $element object contains the address information, including the new address_id.

  • &$element: The created address object.

onAfterAddressUpdate(&$element)

Triggered after an address is successfully updated. The $element object contains the updated address information.

  • &$element: The updated address object.

onBeforeAddressDelete(&$ids, &$do)

Triggered before one or more addresses are deleted. The $ids variable is an array of address IDs. Setting $do to false cancels the deletion.

  • &$ids: An array of address IDs to be deleted.
  • &$do: A boolean. Set it to false to cancel the deletion.

onAfterAddressDelete(&$ids)

Triggered after one or more addresses are successfully deleted. The $ids variable is an array of address IDs.

  • &$ids: An array of deleted address IDs.

onUserAddressesLoad(&$addresses, $user_id, $type)

Triggered when HikaShop loads user addresses (e.g., when displaying the address selection during checkout).

  • &$addresses: An array of address objects found in the database. You can modify this array (add, remove, or change address objects).
  • $user_id: The ID of the user whose addresses are being loaded.
  • $type: The type of addresses being loaded ("both", "billing", or "shipping").

onUserAddressLoad(&$address, $address_id)

Triggered when HikaShop loads a single address from the database.

  • &$address: The address object.
  • $address_id: The ID of the address being loaded.

 

Shipping API

This API allows you to perform actions related to shipping methods and price calculations.

Available events for the Shipping API:

onShippingDisplay(&$order, &$methods, &$available_methods)

Triggered when shipping methods are displayed during checkout. $available_methods contains the methods that will be shown to the customer.

  • &$order: The order object.
  • &$methods: An array of eligible shipping method objects.
  • &$available_methods: An array of shipping methods that will be available for selection.

Suppose that you are making a shipping plugin for a shipping service like UPS. Here, you would first filter your method options out of the $methods array. Then, connect to the UPS web service to decide, based on the $order information, what shipping methods are possible, and finally add them to the $usable_methods. And if the UPS server returns several shipping services for a situation, you can potentially clone the method object to have several of them in $usable_methods. And since you can't have two shipping methods with the same id, you'll have to append an extra code for each cloned shipping method's shipping_id, and then implement the shippingMethods method in your plugin to provide HikaShop with a list of the possible ids. We would recommend you check the code of plugins/hikashopshipping/ups2 as this is not easy to do without basing yourself on an example.

You can add error messages to the $messages in case no shipping methods were found.

For some shipping carriers, you'll have to propose a selection mechanism (for example, to select a pickup point via a widget provided by the carrier API). You can do so by adding your HTML in an attribute "custom_html" in the object of the shipping method, before adding it to the $usable_methods array. In it, you'll want to have a hidden input with the name constructed like this: 

$name = 'checkout[shipping][custom]'.(isset($order->shipping_warehouse_id) ? ('['.$order->shipping_warehouse_id.']') : '').'['.$rate->shipping_id.']';

This way, HikaShop will display your custom HTML automatically when the shipping method of your plugin is displayed. It will also save it into the cart automatically for you. The data will be available in $cart->cart_params->shipping in places where the cart object is available.
Also, you can implement the method onShippingCustomSave($cart, $method, $group, $data) in your plugin. This method will be called when the checkout receives the data from the hidden input in your custom_html. $cart will contain the cart data, $method will contain the data of your shipping method. $group will be the warehouse id, and $data will be the data provided by your hidden input. If your method returns false, you can prevent HikaShop from saving the data in $cart->cart_params->shipping.

If you wish to display an error message to the customer when the hidden input of your custom html is not filled, you can implement the onBeforeCartSave event of the Cart API in your plugin. There, check if check if data is provided in the correct subarray (based on the warehouse id and the shipping id of your shipping method). If checkout[shipping][custom] is available in the POST but the data is not provided in the correct subarray, then you can cancel the cart save and use the enqueueMessage method of Joomla to display an error message to the user.

 

onShippingSave(&$order, &$methods, &$shipping_id)

Triggered when the shipping method is saved during checkout. $shipping_id is the ID of the selected shipping method.

  • &$order: The order object.
  • &$methods: The array of shipping methods.
  • &$shipping_id: The selected shipping method ID (string).

Suppose that you are making a shipping plugin for a shipping service like UPS. Here, you would first filter your method options out of the $methods array. Then, you could get the list of usable methods that you would have cached in the session in the function onShippingDisplay and see if the selected method is in them.

 

onShippingUpdate(&$order, &$methods, &$shipping_id)

Triggered when the shipping method is updated during the checkout process.

onShippingPriceCheck(&$order, &$methods, &$shipping_id, &$price)

Triggered when HikaShop calculates the shipping price. You can use it to modify the $price object before it's displayed or saved.

  • &$order: The order object.
  • &$methods: The array of shipping methods.
  • &$shipping_id: The ID of the selected shipping method.
  • &$price: The price object containing price_value, price_value_with_tax, and taxes.

onShippingConfiguration(&$element)

Triggered on the backend shipping method configuration page. Use this to display additional configuration fields.

  • &$element: The shipping method object.

onShippingConfigurationSave(&$element)

Triggered when the shipping method configuration is saved in the backend. In most cases, you won't have to use this function.

  • &$element: The shipping method object being saved.

 

 

shippingMethods(&$method)

Triggered when a dropdown of shipping methods is displayed (e.g., in payment plugins' "shipping methods" option or order details). Return an array like array('ID1'=>'Name 1','ID2'=>'Name 2').

  • &$method: The shipping method plugin instance.

You can look at the UPS shipping plugin for an example of implementation.

onAfterProcessShippings(&$usable_methods)

Triggered after usable shipping methods have been determined. Allows reprocessing or extra modifications once available shipping methods are known.

  • &$usable_methods: An array of shopping rate objects.

 

 

Payment API

This API allows you to perform actions related to payment methods and price calculations.

Available events for the Payment API:

onPaymentDisplay(&$order, &$methods, &$available_methods)

Triggered when payment methods are displayed during checkout. $available_methods contains the methods that will be shown to the customer.

  • &$order: The order object.
  • &$methods: An array of eligible payment method objects.
  • &$available_methods: An array of payment methods that will be available for selection.

 

onPaymentSave(&$order, &$methods, &$payment_id)

Triggered when a payment method is saved during checkout. $payment_id is the ID of the selected payment method.

  • &$order: The order object.
  • &$methods: The array of payment methods.
  • &$payment_id: The selected payment method ID (string).

 

onPaymentUpdate(&$order, &$methods, &$payment_id)

Triggered when a payment method is updated during the checkout process.

  • &$order: The order object.
  • &$methods: The array of payment methods.
  • &$payment_id: The updated payment method ID.

onPaymentPriceCheck(&$order, &$methods, &$payment_id, &$price)

Triggered when HikaShop calculates the payment method price. You can use it to modify the $price object.

  • &$order: The order object.
  • &$methods: The array of payment methods.
  • &$payment_id: The ID of the selected payment method.
  • &$price: The price object containing price_value, price_value_with_tax, and taxes.

onPaymentConfiguration(&$element)

Triggered on the backend payment method configuration page. Use this to display additional configuration fields.

  • &$element: The payment method object.

 

onPaymentConfigurationSave(&$element)

Triggered when the payment method configuration is saved in the backend. In most cases, you won't have to use this function.

  • &$element: The payment method object being saved.

 

onAfterOrderConfirm(&$order,&$methods,$method_id)

Triggered when the order payment is confirmed. This is usually where you initiate the redirect to the payment gateway or perform final processing.

  • &$order: The order object.
  • &$methods: An array of eligible method objects (payment or shipping).
  • $method_id: The ID of the selected method.

In the information sent to it, you will probably be able to specify a notification url. You might want to use a url like this: http://yourwebsite.com/index.php?option=com_hikashop&ctrl=checkout&task=notify¬if_payment=PAYMENT_PLUGIN_NAME&tmpl=component&lang=CURRENT_LANG_CODE where PAYMENT_PLUGIN_NAME and yourwebsite.com need to be replaced by your information. That will allow you to have the function onPaymentNotification of your plugin being triggered when hikashop receives a notification. Also, we highly recommend to add the lang parameter and replace CURRENT_LANG_CODE with the current 2 letter code of the current language so that the "status changed" email going to the user will be translated in the user's language.

We invite you to look at the paypal payment plugin for an example of implementation

 

onPaymentNotification(&$statuses)

Triggered when a payment notification (webhook) is received for your plugin. Here you will have to make sure that the notification is secure and then you will be able to update the order based on the payment information.

  • &$statuses: An array containing the available order statuses. You can map the gateway status to a HikaShop order status.

 

onAfterProcessPayments(&$usable_rates, &$cart)

Triggered after payment methods have been processed and their prices (including taxes) calculated.

  • &$usable_rates: Array of processed payment method objects.
  • &$cart: The current cart object.

 

Vote API

This API allows you to perform actions related to the HikaShop voting system.

Available events for the Vote API:

onBeforeVoteCreate(&$element, &$do, &$errors)

Triggered before a vote or comment is created.

  • &$element: The vote object.
  • &$do: Boolean to allow or cancel.
  • &$errors: Array of error messages.

onAfterVoteCreate(&$element, &$return_data)

Triggered after a vote or comment is created.

  • &$element: The created vote object.
  • &$return_data: Array containing average rating and total votes.

onBeforeVoteUpdate(&$element, &$do, &$oldElement, &$errors)

Triggered before a vote is updated.

  • &$element: The updated vote object.
  • &$do: Boolean to allow or cancel.
  • &$oldElement: The original vote object before changes.
  • &$errors: Array of error messages.

onAfterVoteUpdate(&$element, &$return_data)

Triggered after a vote is updated.

  • &$element: The updated vote object.
  • &$return_data: Array containing the new average and total.

onBeforeVoteDelete(&$elements, &$do, &$currentElements)

Triggered before one or more votes are deleted.

  • &$elements: Array of vote IDs.
  • &$do: Boolean to allow or cancel.
  • &$currentElements: Array of vote objects being deleted.

onAfterVoteDelete(&$elements)

Triggered after one or more votes are deleted.

  • &$elements: Array of deleted vote IDs.

Cart API

 

onBeforeCartUpdate(&$cartClass,&$cart,$product_id,$quantity,$add,$type,$resetCartWhenUpdate,$force,&$do) DEPRECATED use onBeforeCartSave instead

This event will be triggered by HikaShop before the cart is updated, the object $cartClass is the instance of the cart class which calls that event, $cart has the existing or the new cart information, $product_id is a variable with the id of the product added in the cart.
$quantity is the quantity of the product to add to the cart, the $add variable says whether the quantity replaces the quantity of the product already in the cart or is added to it, and finally, $type is a variable containing the type of the item to update generally 'product'

onBeforeCartSave(&$element,&$do)

This event will be triggered by HikaShop before the cart is saved, when a product is added, removed, modified, when a shipping or payment method is selected, etc. In the object $element, you can have an attribute cart_products which is an array of products to be added/modified. You can use the variable $do to cancel the save.

onAfterCartUpdate(&$cartClass,&$cart,$product_id,$quantity,$add,$type,$resetCartWhenUpdate,$force) DEPRECATED use onAfterCartSave instead

This event will be triggered by HikaShop after the cart is updated, the object $cartClass is the instance of the cart class which calls that event, $cart has the existing or the new cart information, $product_id is a variable with the id of the product added in the cart.
$quantity is the quantity of the product to add to the cart, the $add variable says whether the quantity replaces the quantity of the product already in the cart or is added to it, and finally, $type is a variable containing the type of the item to update generally 'product'

onAfterCartSave(&$element)

This event will be triggered by HikaShop after the cart is saved, when a product is added, removed, modified, when a shipping or payment method is selected, etc. In the object $element, you can have an attribute cart_products which is an array of products which were added/modified.

onBeforeCartProductsLoad(&$cart, &$options, &$filters)

This event will be triggered by HikaShop when the cart is being loaded, just before the cart products data is loaded. The object $cart contains all the cart data that is already loaded at that point. The $options array contains option values used when loading carts. The $filters array contains an array of MySQL conditions for the loading of the products.

onAfterCheckCartQuantities(&$cart, $parent_products, &$ret)

Triggered after all product quantities in the cart have been checked against stock and limitations.

  • &$cart: The cart object.
  • $parent_products: An array of parent product objects for variants.
  • &$ret: A boolean indicating if the cart quantities are valid.

onAfterCartProductsLoad(&$cart)

Triggered when the cart is loaded, after all product data has been retrieved.

  • &$cart: The cart object with its loaded products.

onAfterCartCouponLoad(&$cart)

Triggered when the cart is loaded, after the coupon has been applied.

  • &$cart: The cart object.

onAfterCartShippingLoad(&$cart)

Triggered when the cart is loaded, after the shipping method has been applied.

  • &$cart: The cart object.

onHikaShopCartSelectPayment(&$cart, &$cart_payment_id)

Triggered when a payment method is auto-selected for the cart. You can modify $cart_payment_id to change the selection.

  • &$cart: The cart object.
  • &$cart_payment_id: The ID of the selected payment method.

onAfterFullCartLoad(&$cart)

Triggered at the very end of the cart loading process, once everything (products, addresses, shipping, payment, coupons) is finalized.

  • &$cart: The full cart object.

onAfterProductQuantityCheck(&$product, &$wantedQuantity, &$quantity, &$cartContent, &$cart_product_id_for_product, &$displayErrors)

Triggered to check if a product is purchasable. $wantedQuantity is what the user requested, and $quantity is the allowed amount. Set $quantity to 0 to prevent purchase. Set $displayErrors to false to suppress HikaShop's default error messages.

  • &$product: The product object being checked.
  • &$wantedQuantity: The quantity requested by the user.
  • &$quantity: The quantity allowed by HikaShop (can be modified).
  • &$cartContent: The current whole content of the cart.
  • &$cart_product_id_for_product: The ID of the product in the cart.
  • &$displayErrors: Boolean to control error message display.

onGetCartProductsInfo(&$cart, &$ret)

Triggered when returning cart data to JavaScript. $ret is the array of data sent to the JS side. Anything added to $ret will be available in the cart.update JS event.

  • &$cart: The cart object.
  • &$ret: An associative array of data to be sent to the frontend.

onBeforeCartLoad(&$cart, &$options)

Triggered before HikaShop loads a cart from the database. $options allows you to customize the loading process.

  • &$cart: The cart object.
  • &$options: An array of options for loading the cart.

onAfterCartLoad(&$cart, &$options)

Triggered after a cart is loaded but before it's returned. Use this to modify the $cart object after it has been populated from the database.

  • &$cart: The loaded cart object.
  • &$options: The options used for loading.

onBeforeCartDelete(&$elements, &$do)

Triggered before one or more carts are deleted. $elements is an array of cart IDs. Setting $do to false cancels the deletion.

  • &$elements: An array of cart IDs to be deleted.
  • &$do: A boolean. Set it to false to cancel the deletion.

onAfterCartDelete(&$elements)

Triggered after one or more carts are successfully deleted.

  • &$elements: An array of deleted cart IDs.

onBeforeProductQuantityCheck(&$products, &$cart, &$options)

Triggered before checking product quantities in the cart. It allows plugins to modify products or options before HikaShop performs its own checks (stock, limits, dates).

  • &$products: The list of products being added or updated.
  • &$cart: The current cart object.
  • &$options: Additional options for the check.

onCompareCartProducts($p, $cart_product, &$do)

Triggered when HikaShop compares Two products to see if they should be grouped in the cart. Set $do = false to force them to be separate items.

  • $p: The first product object.
  • $cart_product: The second product object.
  • &$do: A boolean. Set it to false to prevent grouping.

onBeforeCheckCartQuantities(&$cart, &$parent_products)

Triggered at the beginning of the checkCartQuantities process (modern checkout) to allow global stock/limitation pre-checks.

  • &$cart: The cart object.
  • &$parent_products: An array of parent product objects for variants.

 

 

Checkout API

This API allows you to customize the HikaShop checkout workflow.

Available events for the Checkout API:

 

onCheckoutStepList(&$list)

Triggered on the configuration page. Add your custom views to $list (e.g., $list['plg.shop.myview'] = 'My Custom View') so they can be placed in the checkout workflow.

  • &$list: An associative array of workflow block types. Keys are internal names, values are display names.

onBeforeCheckoutStep($controller, &$go_back, $original_go_back, &$controller)

Note: This event is deprecated and only applies to the legacy checkout. Use onCheckoutStepDisplay instead.

onAfterCheckoutStep($controllerName, &$go_back, $original_go_back, &$controller)

Triggered when the user clicks "Next" on a checkout step. Use this to validate or process data from your view. Set $go_back to true to prevent moving to the next step.

  • $controllerName: The name of the current controller.
  • &$go_back: Boolean. Set to true to block progression and stay on the current step.
  • $original_go_back: The initial state of the go_back flag.
  • &$controller: The checkout controller instance.

onInitCheckoutStep($task, &$view)

Triggered when a checkout step or block is initialized. Use this to prepare data required for your custom checkout blocks.

  • $task: The task/block name being initialized.
  • &$view: The checkout view object.

onBeforeCheckoutViewDisplay($layoutName, &$view)

Triggered before a checkout layout (block) is displayed. $layoutName is the name of the block (e.g., 'cart', 'login').

  • $layoutName: The name of the current layout/block.
  • &$view: The checkout view object.

onAfterCheckoutViewDisplay($layoutName, &$view, &$html)

Triggered after a checkout layout is displayed. $html contains the generated HTML of the block.

  • $layoutName: The name of the current layout/block.
  • &$view: The checkout view object.
  • &$html: The generated HTML output of the block.

onCheckoutStepDisplay($layoutName, &$html, &$view, $pos, $options)

Triggered when a non-standard checkout block needs to be displayed.

  • $layoutName: The name of the custom task.
  • &$html: The HTML output (append your content here).
  • &$view: The checkout view object.
  • $pos: The position of the block in the workflow step.
  • $options: The configuration options of the block.

onCheckoutEmptyContentCheck(&$controller, &$params, &$empty)

Triggered when HikaShop checks if a checkout step is empty. Use this to dynamically show or hide custom checkout blocks.

  • &$controller: The checkout controller object.
  • &$params: The block parameters.
  • &$empty: A boolean indicating if the block is empty. Set it to false to force display.

onCheckoutWorkflowLoad(&$checkout_workflow, &$shop_closed, $cart_id)

Triggered after the checkout workflow is loaded. Perfect for dynamically changing the workflow or closing the checkout ($shop_closed = true).

  • &$checkout_workflow: The workflow structure.
  • &$shop_closed: Boolean to block the checkout process.
  • $cart_id: The ID of the cart being processed.

 

 

Display API

This API allows you to customize the display of various elements in HikaShop.

Available events for the Display API:

onDisplayImport(&$importData)

Triggered when displaying the import interface. $importData is an array with the data for each tab.

  • &$importData: An associative array where keys are tab identifiers and values are data objects for those tabs.

onProductFormDisplay(&$element, &$html)

Triggered when displaying the product form in the backend.

  • &$element: The product object being displayed.
  • &$html: The HTML content. You can append your custom HTML here.

onProductDisplay(&$element, &$html)

Triggered when displaying a product edit page in the backend.

  • &$element: The product object.
  • &$html: The HTML content.

onProductBlocksDisplay(&$element, &$html)

Triggered when displaying the blocks of the product in the backend.

  • &$element: The product object.
  • &$html: The HTML content.

onAfterOrderProductsListingDisplay(&$order, $mail)

Triggered after displaying the listing of products in an order. $order is an object containing order data.

  • &$order: The order object.
  • $mail: A boolean. true if the display is for an email, false otherwise.

onHikashopBeforeDisplayView(&$view)

Triggered before displaying a view. $view is the view instance. You can use $view->getName() and $view->getLayout() to target specific views. This event is commonly used to inject extra columns or data into backend listings.

  • &$view: The view object instance.

onHikashopAfterDisplayView(&$view)

Triggered after a view is displayed.

  • &$view: The view object instance.

Views API

This API allows you to interact with the view override system in the backend of HikaShop.

onViewsListingLoad(&$templates, &$pageInfo)

Triggered to collect available views for the views listing in the backend. Plugins can use this to add their own views to the list, allowing users to override them through the HikaShop interface.

  • &$templates: An array of view objects.
  • &$pageInfo: Information about pagination and search.

onBeforeViewUpdate(&$element, &$do)

Triggered before a view override is saved. Set $do = false to cancel.

  • &$element: The view object being saved.
  • &$do: A boolean. Set it to false to cancel the update.

onAfterViewUpdate(&$element)

Triggered after a view override is saved.

  • &$element: The saved view object.

onBeforeViewDelete(&$element, &$do)

Triggered before a view override is deleted.

  • &$element: The view object to be deleted.
  • &$do: A boolean. Set it to false to cancel the deletion.

onAfterViewDelete(&$element)

Triggered after a view override is deleted.

  • &$element: The deleted view object.

 

public function onHikashopBeforeDisplayView(&$view) {
    if(!hikashop_isClient('administrator'))
        return;
    if($view->getName() != 'order' || $view->getLayout() != 'listing')
        return;

    if(empty($view->extrafields))
        $view->extrafields = array();

    $column = new stdClass();
    $column->name = JText::_('MY_EXTRA_COLUMN');
    $column->value = 'extra_column';
    $view->extrafields['extra_column'] = $column;

    if(!empty($view->rows)) {
        foreach($view->rows as $k => $row) {
            $view->rows[$k]->extra_column = 'HTML Content';
        }
    }
}

 

Coupon API

This API allows you to customize coupon loading and validation.

Available events for the Coupon API:

onBeforeCouponLoad(&$coupon, &$do)

Triggered before loading a coupon. Setting $do to false cancels the loading.

  • &$coupon: The coupon code string or object.
  • &$do: A boolean. Set it to false to cancel the loading.

onBeforeCouponCheck(&$coupon, &$total, &$zones, &$products, &$display_error, &$error_message, &$do)

Triggered before validating a coupon. You can modify the coupon values, set $display_error to false to hide default errors, or provide a custom $error_message. Setting $do to false skips HikaShop's default checks.

  • &$coupon: The coupon object.
  • &$total: The total object.
  • &$zones: An array of zone IDs.
  • &$products: An array of product objects in the cart.
  • &$display_error: A boolean. Set it to false to suppress the default error message.
  • &$error_message: A string. Provide a custom message if validation fails.
  • &$do: A boolean. Set it to false to skip default HikaShop validation.

onAfterCouponCheck(&$coupon, &$total, &$zones, &$products, &$display_error, &$error_message, &$do)

Triggered after a coupon is checked but before it is processed.

  • &$coupon: The coupon object.
  • &$total: The total object.
  • &$zones: An array of zone IDs.
  • &$products: An array of product objects.
  • &$display_error: A boolean.
  • &$error_message: A string.
  • &$do: A boolean.

 

Discount API

This API allows you to customize how discounts and coupons are handled.

Available events for the Discount API:

onBeforeDiscountCreate(&$discount, &$do)

Triggered before a discount or coupon is created. Setting $do to false cancels the creation.

  • &$discount: The discount object to be created.
  • &$do: A boolean. Set it to false to cancel the creation.

onBeforeDiscountUpdate(&$discount, &$do)

Triggered before a discount or coupon is updated. Setting $do to false cancels the update.

  • &$discount: The discount object to be updated.
  • &$do: A boolean. Set it to false to cancel the update.

onAfterDiscountCreate(&$discount)

Triggered after a discount or coupon is successfully created.

  • &$discount: The created discount object.

onAfterDiscountUpdate(&$discount)

Triggered after a discount or coupon is successfully updated.

  • &$discount: The updated discount object.

onBeforeDiscountDelete(&$ids, &$do)

Triggered before one or more discounts are deleted. Setting $do to false cancels the deletion.

  • &$ids: An array of discount IDs to be deleted.
  • &$do: A boolean. Set it to false to cancel the deletion.

onAfterDiscountDelete(&$ids)

Triggered after one or more discounts are successfully deleted.

  • &$ids: An array of deleted discount IDs.

onBeforeLoadProductPriceDiscount(&$filters, $rows, $trigger_options)

Triggered before HikaShop loads discounts for a list of products.

  • &$filters: An array of WHERE clauses (strings) for the discount query.
  • $rows: An array of product objects for which discounts are being loaded.
  • $trigger_options: An associative array of context options (user_id, zone_id, currency_id, etc).

onAfterLoadProductPriceDiscount(&$discounts, &$rows, $filters, $trigger_options)

Triggered after discounts have been loaded from the database but before they are applied to price calculations.

  • &$discounts: An array of discount objects loaded from the database.
  • &$rows: The product objects.
  • $filters: The filters used in the query.
  • $trigger_options: The context options.

onBeforeDiscountOnlyCheckQuery(&$selects, &$joins, &$discount_filter)

Triggered before the query that checks for available discounts in "Discounted products only" listings.

  • &$selects: Array of columns to select.
  • &$joins: Array of JOIN clauses.
  • &$discount_filter: Array of WHERE clauses.

onAfterDiscountOnlyCheckQuery(&$discounts, &$join_discount_links, &$filters)

Triggered after the discount check query.

  • &$discounts: The result of the query.
  • &$join_discount_links: Array of JOIN conditions for the main product query.
  • &$filters: Array of WHERE clauses for the main product query.

onDiscountBlocksDisplay(&$element, &$html)

Triggered when displaying the discount/coupon edit form in the backend. Use this to inject custom configuration blocks.

 

User API

This API allows you to perform actions related to HikaShop users.

Available events for the User API:

onBeforeUserCreate(&$element, &$do)

Triggered before a HikaShop user is created.

  • &$element: The user object to be created.
  • &$do: A boolean. Set it to false to cancel the creation.

onBeforeUserUpdate(&$element, &$do)

Triggered before a HikaShop user is updated.

  • &$element: The user object with updated information.
  • &$do: A boolean. Set it to false to cancel the update.

onAfterUserCreate(&$element)

Triggered after a HikaShop user is successfully created.

  • &$element: The created user object, including the user_id.

onAfterUserUpdate(&$element)

Triggered after a HikaShop user is successfully updated.

  • &$element: The updated user object.

onBeforeUserDelete(&$ids, &$do)

Triggered before one or more HikaShop users are deleted.

  • &$ids: An array of HikaShop user IDs.
  • &$do: A boolean. Set it to false to cancel the deletion.

onAfterUserDelete(&$ids)

Triggered after one or more HikaShop users are successfully deleted.

  • &$ids: An array of deleted user IDs.

onUserAccountDisplay(&$buttons)

Triggered when displaying the user control panel. You can add or remove buttons from the $buttons array.

  • &$buttons: An array of button objects.

onUserControlPanelDisplay(&$html)

Triggered when displaying the user control panel.

  • &$html: The HTML content.

onBeforeUserListing($paramBase, &$extrafilters, &$pageInfo, &$filters, &$tables, &$searchMap, &$select)

Triggered before HikaShop loads users for a listing.

  • $paramBase: The base URL parameters.
  • &$extrafilters: Extra filters (array).
  • &$pageInfo: Pagination information.
  • &$filters: Query filters (array).
  • &$tables: Joins (array).
  • &$searchMap: Search map (array).
  • &$select: Select clauses (array).

onBeforeHikaUserRegistration(&$ret, $input_data, $mode)

Triggered during HikaShop user registration, before the Joomla user is created. It allows plugins to perform additional validation or modify the registration data.

  • &$ret: An associative array containing the status and messages of the registration. It also contains references to registerData, userData, addressData, and shippingAddressData.
  • $input_data: The raw input data for user registration.
  • $mode: The registration mode (0: Registration, 1: Simplified, 2: Guest, 3: Simplified with password).

onAfterHikaUserRegistration(&$ret, $input_data, $mode, &$send_email)

Triggered after the HikaShop user registration process is complete but before the confirmation email is sent.

  • &$ret: The registration result array (same as onBeforeHikaUserRegistration).
  • $input_data: The raw input data.
  • $mode: The registration mode.
  • &$send_email: A boolean indicating if a confirmation email should be sent.

 

Fields API

This API allows you to customize custom fields behaviors.

Available events for the Fields API:

onFieldDateDisplay($field_namekey, $field, &$value, &$map, &$format, &$size)

Triggered when displaying a custom field of type "Date".

  • $field_namekey: Internal name key of the field.
  • $field: The field object.
  • &$value: The current value of the field.
  • &$map: A mapping object for the date picker.
  • &$format: The date format string.
  • &$size: Size of the input field.

onFieldDateCheckSelect(&$values)

Triggered when a date field is selected.

onFieldsLoad(&$externalValues)

Triggered when custom fields are being loaded. Allows to inject external values for custom field selection.

  • &$externalValues: An associative array where keys are field names and values are arrays of options.

Order Status API

This API allows you to customize the behavior of order statuses.

Available events for the Order Status API:

onBeforeOrderstatusCreate(&$element, &$do)

Triggered before a new order status is created.

  • &$element: The order status object.
  • &$do: Boolean to allow or cancel.

onAfterOrderstatusCreate(&$element)

Triggered after a new order status is successfully created.

  • &$element: The created order status object.

onBeforeOrderstatusUpdate(&$element, &$do)

Triggered before an existing order status is updated.

  • &$element: The order status object with new data. $element->old contains previous data.
  • &$do: Boolean to allow or cancel.

onAfterOrderstatusUpdate(&$element)

Triggered after an order status is successfully updated.

  • &$element: The updated order status object.

onBeforeOrderstatusDelete(&$ids, &$do)

Triggered before one or more order statuses are deleted.

  • &$ids: Array of order status IDs.
  • &$do: Boolean to allow or cancel.

onAfterOrderstatusDelete(&$ids)

Triggered after one or more order statuses are successfully deleted.

  • &$ids: Array of deleted order status IDs.

onOrderStatusListingLoad(&$filters, &$order, &$view)

Triggered when loading the order status list in the backend. You can use this to add custom columns or filters.

  • &$filters: Array of WHERE clauses.
  • &$order: The ORDER BY clause.
  • &$view: The view object.

 

Filter API

This API allows you to perform actions related to the HikaShop filtering system.

Available events for the Filter API:

onBeforeFilterCreate(&$element, &$do)

Triggered before a filter is created.

  • &$element: The filter object.
  • &$do: Boolean to allow or cancel.

onAfterFilterCreate(&$element)

Triggered after a filter is successfully created.

  • &$element: The created filter object.

onBeforeFilterUpdate(&$element, &$do)

Triggered before a filter is updated.

  • &$element: The updated filter object.
  • &$do: Boolean to allow or cancel.

onAfterFilterUpdate(&$element)

Triggered after a filter is successfully updated.

  • &$element: The updated filter object.

onBeforeFilterDelete(&$ids, &$do)

Triggered before one or more filters are deleted.

  • &$ids: Array of filter IDs.
  • &$do: Boolean to allow or cancel.

onAfterFilterDelete(&$ids)

Triggered after one or more filters are successfully deleted.

  • &$ids: Array of deleted filter IDs.

onFilterDisplay(&$filter, &$html, &$divName, &$parent, &$datas)

Triggered when a filter is displayed. Use this for custom filter types.

  • &$filter: The filter object.
  • &$html: The HTML content to display.
  • &$divName: The name of the div containing the filter.
  • &$parent: The parent object (usually the product listing).
  • &$datas: Data used by the filter.

onFilterAdd(&$filter, &$filters, &$select, &$select2, &$a, &$b, &$on, &$order, &$divName, &$parent)

Triggered when a filter needs to be added to the SQL query.

  • &$filter: The filter object.
  • &$filters: Array of WHERE clauses.
  • &$select: Array of SELECT clauses.
  • &$select2: Array of secondary SELECT clauses.
  • &$a: Tables for joins.
  • &$b: Tables for joins.
  • &$on: JOIN conditions.
  • &$order: The ORDER BY clause.
  • &$divName: The div name.
  • &$parent: The parent object.

onFilterToLoad(&$filter, &$html, &$divName, &$parent)

Triggered when loading the fields for a filter.

  • &$filter: The filter object.
  • &$html: The HTML content.
  • &$divName: The div name.
  • &$parent: The parent object.

Currency and Taxation API

This API allows you to customize price rounding, currency conversion, and taxation rules.

Available events for the Currency and Taxation API:

onBeforeCurrencyCreate(&$element, &$do)

Triggered before a currency is created.

  • &$element: The currency object.
  • &$do: Boolean to allow or cancel.

onAfterCurrencyCreate(&$element)

Triggered after a currency is successfully created.

  • &$element: The created currency object.

onBeforeCurrencyUpdate(&$element, &$do)

Triggered before a currency is updated.

  • &$element: The currency object.
  • &$do: Boolean to allow or cancel.

onAfterCurrencyUpdate(&$element)

Triggered after a currency is successfully updated.

  • &$element: The updated currency object.

onBeforeCurrencyDelete(&$ids, &$do)

Triggered before one or more currencies are deleted.

  • &$ids: Array of currency IDs.
  • &$do: Boolean to allow or cancel.

onAfterCurrencyDelete(&$ids)

Triggered after one or more currencies are successfully deleted.

  • &$ids: Array of deleted currency IDs.

onBeforeTaxCreate(&$element, &$do)

Triggered before a tax rate is created.

  • &$element: The tax object.
  • &$do: Boolean to allow or cancel.

onBeforeTaxationCreate(&$element, &$do)

Triggered before a taxation rule (linking tax to zone/category) is created.

  • &$element: The taxation object.
  • &$do: Boolean to allow or cancel.

onHikashopGetTax(&$obj, $zone_id, $tax_category_id, $type, &$matches, &$taxPlans)

Triggered when HikaShop determines which taxes apply to a specific situation.

  • &$obj: The currency helper instance.
  • $zone_id: The zone ID (shipping or billing address).
  • $tax_category_id: The product's tax category ID.
  • $type: The type of tax.
  • &$matches: The array of matching taxation rules found so far.
  • &$taxPlans: The array of all available taxation rules.

 

 

 

Waitlist API

This API allows you to perform actions related to the waitlist system.

Available events for the Waitlist API:

onBeforeWaitlistCreate(&$element, &$do)

Triggered before a waitlist entry is created.

  • &$element: The waitlist object.
  • &$do: Boolean to allow or cancel.

onAfterWaitlistCreate(&$element)

Triggered after a waitlist entry is successfully created.

  • &$element: The created waitlist object.

onBeforeWaitlistUpdate(&$element, &$do)

Triggered before a waitlist entry is updated.

  • &$element: The updated waitlist object.
  • &$do: Boolean to allow or cancel.

onAfterWaitlistUpdate(&$element)

Triggered after a waitlist entry is successfully updated.

  • &$element: The updated waitlist object.

onBeforeWaitlistDelete(&$ids, &$do)

Triggered before one or more waitlist entries are deleted.

  • &$ids: Array of waitlist IDs.
  • &$do: Boolean to allow or cancel.

onAfterWaitlistDelete(&$ids)

Triggered after one or more waitlist entries are successfully deleted.

  • &$ids: Array of deleted waitlist IDs.

 

File API

This API allows you to customize file handling and downloads.

Available events for the File API:

onBeforeDownloadFile(&$filename, &$do, &$file)

Triggered before a file download.

  • &$filename: The path to the file.
  • &$do: A boolean. Set it to false to cancel the download.
  • &$file: The file object from the database.

onBeforeFileCreate(&$file, &$do)

Triggered before a file (image or download) is created in the database.

  • &$file: The file object.
  • &$do: Boolean to allow or cancel.

onAfterFileCreate(&$file)

Triggered after a file is successfully created.

  • &$file: The created file object.

onBeforeFileUpdate(&$file, &$do)

Triggered before a file is updated.

  • &$file: The file object with updated data.
  • &$do: Boolean to allow or cancel.

onAfterFileUpdate(&$file)

Triggered after a file is successfully updated.

  • &$file: The updated file object.

onBeforeFileDelete(&$oldEntries)

Triggered before one or more files are deleted.

  • &$oldEntries: Array of file objects to be deleted.

onAfterFileDelete(&$oldEntries)

Triggered after one or more files are successfully deleted.

  • &$oldEntries: Array of deleted file objects.

onHikaBeforeFileSave(&$file, &$do)

Triggered before a file is saved during product or category editing.

  • &$file: The file object.
  • &$do: Boolean to allow or cancel.

onHikaAfterFileSave(&$file)

Triggered after a file is successfully saved during product or category editing.

  • &$file: The saved file object.

Email API

This API allows you to customize email preparation, sending and registration.

onBeforeMailPrepare(&$mail, &$mailer, &$do)

Triggered before an email is prepared for sending. Allows to modify the mail content or cancel sending.

  • &$mail: The mail object containing data (to, subject, body, options).
  • &$mailer: The HikaShop mailer instance.
  • &$do: A boolean. Set it to false to cancel the email preparation and sending.

onBeforeMailSend(&$mail, &$mailer)

Triggered just before an email is sent.

  • &$mail: The mail object with its final content.
  • &$mailer: The HikaShop mailer instance.

onMailListing(&$plugin_files)

Allows plugins to register custom emails in System > Emails. Add your email metadata to $plugin_files.

  • &$plugin_files: An array of email configuration objects.

 

Configuration API

This API allows you to customize HikaShop settings loading and saving.

onAfterConfigLoad(&$values)

Triggered after HikaShop configuration is loaded from the database.

  • &$values: Array of configuration objects.

onBeforeConfigSave(&$config, &$do)

Triggered before HikaShop configuration is saved.

  • &$config: The configuration array.
  • &$do: Boolean to allow or cancel.

onAfterConfigSave(&$params)

Triggered after HikaShop configuration is saved.

  • &$params: The parameters that were saved.

 

Mass Action API

This API allows you to create your own data tables, triggers, filters and actions for the HikaShop Mass Action system.

onMassactionTableLoad(&$tables)

Triggered to collect available data tables for mass actions.

  • &$tables: An array of table objects. Each object should have table (internal name) and name (display name) properties.

onMassactionTableTriggersLoad(&$table, &$triggers, &$triggers_html, &$massaction)

Triggered to load triggers for a specific table.

  • $table: The table object.
  • &$triggers: An associative array of trigger names keyed by their internal ID.
  • &$triggers_html: An associative array of HTML for trigger configuration keyed by their internal ID.
  • $massaction: The current mass action object.

onMassactionTableFiltersLoad(&$table, &$filters, &$filters_html, &$massaction)

Triggered to load filters for a specific table. Parameters are similar to triggers.

onMassactionTableActionsLoad(&$table, &$actions, &$actions_html, &$massaction)

Triggered to load actions for a specific table. Parameters are similar to triggers.

onAfterMassactionCreate(&$element)

Triggered after a mass action is created.

  • &$element: The created mass action object.

onAfterMassactionUpdate(&$element)

Triggered after a mass action is updated.

  • &$element: The updated mass action object.

onHikashopBeforeMassActionExecute(&$element, &$do, &$errors)

Triggered before a mass action is executed.

  • &$element: The mass action object.
  • &$do: Boolean to allow or cancel.
  • &$errors: Array for error messages.

onHikashopAfterMassActionExecute(&$element, &$res)

Triggered after a mass action has been executed.

  • &$element: The mass action object.
  • &$res: The execution result.

We recommend studying the existing mass action plugins in /plugins/hikashop/massaction_.../ for implementation details.

Views API

This API allows you to customize view overrides and listings.

Available events for the Views API:

onBeforeViewUpdate(&$element, &$do)

Triggered before a view override is saved.

  • &$element: The view object containing filename, content, and override path.
  • &$do: Boolean to allow or cancel.

onAfterViewUpdate(&$element)

Triggered after a view override is successfully saved.

  • &$element: The saved view object.

onBeforeViewDelete(&$element)

Triggered before a view override is deleted.

  • &$element: The view object to be deleted.

onViewsListingLoad(&$filters, &$order, &$view)

Triggered when loading the list of views/overrides in the backend.

  • &$filters: Array of WHERE clauses.
  • &$order: The ORDER BY clause.
  • &$view: The view object.

onViewsListingFilter(&$pluginViews, $client_id)

Allows plugins to inject their own view files into the HikaShop view listing for the override system.

  • &$pluginViews: An array of view group/view name strings.
  • $client_id: The Joomla client ID (0 for frontend, 1 for administrator).

Dashboard API

This API allows you to customize the HikaShop backend dashboard.

onBeforeStatisticsLoad(&$dashboardStructure)

Triggered before displaying the backend dashboard. $dashboardStructure contains the layout, blocks, and queries. You can inject your own widgets here.

  • &$dashboardStructure: The configuration object for the dashboard.

 

Other Events

Miscellaneous events for various HikaShop functionalities.

onBeforeHikashopLoad($option)

Triggered early in HikaShop initialization.

  • $option: The component option name (usually com_hikashop).

onAfterHikashopLoad()

Triggered after HikaShop initialization is complete.

onHikashopCronTrigger(&$messages)

Triggered when a HikaShop cron job is executed. Add your logs to $messages.

  • &$messages: An array of log messages (strings).

onHikashopBeforeCheckDB(&$createTable, &$custom_fields, &$structure, &$helper)

Triggered during HikaShop's "Check Database" process. Use this to ensure your plugin's custom tables and columns are correctly defined and maintained.

  • &$createTable: An array of CREATE TABLE SQL statements.
  • &$custom_fields: An array of custom fields to be checked.
  • &$structure: An object representing the database structure.
  • &$helper: The HikaShop DB helper instance.

onHikashopAfterCheckDB(&$messages)

Triggered after the database check is complete.

  • &$messages: An array of success or error messages (strings) from the check.

onHikashopPluginController($ctrl)

Allows plugins to implement their own controllers within HikaShop. This lets you offer custom interfaces without creating a full Joomla component. See plg_hikashop_email_history for a live example.

  • $ctrl: The name of the controller being requested.

onCheckSubscription($subscription_level, &$infos)

Triggered when HikaShop checks the subscription level for special features or updates.

  • $subscription_level: The requested level string.
  • &$infos: An array where you can set the subscription status.

onBeforeSendContactRequest(&$element, &$send)

Triggered before a product contact request is sent.

  • &$element: The object containing contact request data.
  • &$send: A boolean. Set it to false to cancel sending the request.

Assets Management

HikaShop provides helpers to manage JavaScript and CSS assets, ensuring compatibility and avoiding duplicate loading.

Loading HikaShop Libraries

Use hikashop_loadJslib($name) to load common libraries. This method handles both JS and CSS dependencies for each library.

hikashop_loadJslib('jquery');
hikashop_loadJslib('font-awesome');
hikashop_loadJslib('fancybox');
hikashop_loadJslib('owl-carousel');

Available libraries include: jquery, font-awesome, fancybox, owl-carousel, tooltip, otree, opload, vex, notify, creditcard, dropdown, nouislider, swiper, drawer.

Adding Custom Assets

For modern Joomla (J4+), use the Web Asset Manager. This allows you to register assets and their dependencies (like jQuery) once, ensuring they are loaded in the correct order:

if (version_compare(JVERSION, '4.0', '>=')) {
    $wa = JFactory::getDocument()->getWebAssetManager();
    
    // Register your asset (usually done in a joomla.asset.json file, but can be done in PHP)
    $wa->registerAndUseStyle('plg_yourplugin.style', 'plugins/hikashop/yourplugin/style.css');
    $wa->registerAndUseScript('plg_yourplugin.script', 'plugins/hikashop/yourplugin/script.js', [], ['defer' => true], ['jquery']);
} else {
    // Fallback for legacy Joomla
    $doc = JFactory::getDocument();
    $doc->addStyleSheet(JURI::root() . 'plugins/hikashop/yourplugin/style.css');
    $doc->addScript(JURI::root() . 'plugins/hikashop/yourplugin/script.js');
}

For more details, see the Joomla Web Asset Manager documentation.

Main Objects

Common objects passed as parameters to HikaShop events. Understanding their structure is key to effective development.

  • $order: Contains the full order record. Important properties:
    • $order->products: Array of product objects in the order.
    • $order->billing_address / $order->shipping_address: Address objects.
    • $order->order_status: Current status string.
    • $order->order_payment_params / $order->order_shipping_params: Objects where custom metadata can be stored for third-party integrations.
  • $product: Represents a catalog item. Important properties:
    • $product->product_code: Unique SKU.
    • $product->prices: Array of price objects.
    • $product->categories: Array of category IDs.
    • $product->product_parent_id: Used to link variants to their main product.
  • $cart: The current shopping session. Properties include $cart->products, $cart->cart_params, and $cart->cart_shipping_ids.

Overrides

HikaShop provides several ways to customize its behavior and appearance without modifying core files.

View Overrides

You can override any HikaShop view by using the Display > Views menu in the HikaShop backend. This is the recommended way as HikaShop handles the file creation for you.

Manual Override Path: templates/YOUR_TEMPLATE/html/com_hikashop/VIEW_GROUP/VIEW_NAME.php
For example, to override the product page: templates/beez3/html/com_hikashop/product/show.php

For more details on layout customization, see the Layout Customization Guide.

Developer Tip: Enable the "Display view files" setting in HikaShop Configuration > Display > General. Once enabled, HikaShop will output a small comment in the HTML source before each view file it renders, making it easy to identify exactly which file you need to override.

Plugin View Overrides

If a plugin uses $this->showPage('somepage'), you can override its output at: templates/YOUR_TEMPLATE/html/com_hikashop/PLUGIN_NAME/somepage.php

Logic Overrides (Legacy)

Note: Most of these legacy override methods are deprecated in favor of PHP events or standard view overrides.

  • Images: Override product / show_block_img.php instead of hikashop_image.php.
  • Characteristics: Override product / show_block_characteristic.php instead of hikashop_characteristics.php.
  • Quantity Input: Override layouts / quantity.php or use CSS.
  • Buttons: Use CSS or override individual view files.

 

Class Overrides

You can override core HikaShop classes (classes, helpers, types, or controllers) by copying them to your template folder and appending Override to the class name.

Path format: templates/YOUR_TEMPLATE/html/com_hikashop/administrator/XXXX/yyy.override.php

class CategoryControllerOverride extends CategoryController {
    public function listing() {
        // Custom logic here
        return parent::listing();
    }
}

 

Database Structure

HikaShop uses several tables to store its data. All table names are prefixed with your Joomla database prefix followed by hikashop_.

Product Catalog

  • hikashop_product: Stores the main product information (name, description, code, etc.). Products and Variants are both stored here, linked via product_parent_id.
  • hikashop_category: Stores the category tree using a nested set model (category_left, category_right). Used for products, zones, tax rates, etc.
  • hikashop_product_category: Junction table for many-to-many relationship between products and categories.
  • hikashop_characteristic: Stores product characteristics (e.g., Color, Size) and their possible values.
  • hikashop_variant: Stores the relationship between products and characteristics.
  • hikashop_file: Stores metadata about images and downloadable files.

Sales & Orders

  • hikashop_order: Main order header (status, customer, totals, payment/shipping methods).
  • hikashop_order_product: Products included in each order, with snapshot data (price, tax) at the time of purchase.
  • hikashop_history: Detailed log of order status changes and history notes.
  • hikashop_orderstatus: Defines the available order statuses and their configurations.

Shopping Cart

  • hikashop_cart: Temporary cart headers for guest and registered users.
  • hikashop_cart_product: Items currently held in users' carts.

Customer Data

  • hikashop_user: Links HikaShop customers to Joomla users, stores affiliate data and user-specific shop settings.
  • hikashop_address: Stores billing and shipping addresses linked to users.

Logistics & Commerce

  • hikashop_shipping: Configuration for shipping methods.
  • hikashop_payment: Configuration for payment methods.
  • hikashop_warehouse: Store warehouses for product stock management.
  • hikashop_zone: Geographical structure (Countries, States, Tax zones).
  • hikashop_currency: Currencies and exchange rates.

Pricing & Taxes

  • hikashop_price: Product prices. Supports multiple currencies and quantity breaks.
  • hikashop_tax: Base tax rates.
  • hikashop_taxation: Taxation rules linking taxes, zones, and categories.

Marketing & Promotions

  • hikashop_discount: Stores both automatic discounts and manual coupons (distinguished by discount_type).
  • hikashop_badge: Product labels ("New", "Sale").
  • hikashop_banner: Advertisement banners.
  • hikashop_click: Logs for affiliate link clicks.

Technical Tools

  • hikashop_config: Central HikaShop configuration.
  • hikashop_field: Custom fields definitions (Address, User, Product, Order).
  • hikashop_filter: Definitions for product filters.
  • hikashop_massaction: Saved mass action configurations.
  • hikashop_waitlist: Users waiting for stock notifications.
  • hikashop_vote: Product ratings and user reviews.

View Database Diagram

PHP Code Samples

To use HikaShop classes in your own scripts, you must first load the HikaShop helper:

if(!@include_once(JPATH_ADMINISTRATOR . '/components/com_hikashop/helpers/helper.php')) return false;

Get Configuration Settings

Use hikashop_config() to retrieve any setting from the HikaShop configuration.

$config = hikashop_config();
$roundPrices = $config->get('round_prices', 0);

Load a Product

$productClass = hikashop_get('class.product');
$product = $productClass->get($product_id);

if ($product) {
    echo $product->product_name;
}

Load a Category

$categoryClass = hikashop_get('class.category');
$category = $categoryClass->get($category_id);

Add to Cart

$cartClass = hikashop_get('class.cart');
$cartClass->update($product_id, $quantity);

Load Current Cart

$cartClass = hikashop_get('class.cart');
$cart = $cartClass->getFullCart();

foreach($cart->products as $product) {
    echo $product->product_name . '<br/>';
}

Load full Order

$orderClass = hikashop_get('class.order');
$order = $orderClass->loadFullOrder($order_id, true, false);

foreach($order->products as $product) {
    echo $product->product_name . '<br/>';
}

To create a new order programmatically:

$order = new stdClass();
$order->order_full_price = 120.50;
$order->order_currency_id = 1; // ID from hikashop_currency
$order->order_user_id = 42;
$order->order_status = 'created';

// Add a product to the order
$product = new stdClass();
$product->product_id = 10;
$product->order_product_quantity = 2;
$product->order_product_price = 60.25;
$product->order_product_name = 'Example Product';

$order->products = array($product);

$orderClass = hikashop_get('class.order');
$orderClass->save($order);

Update Order Status

$orderClass = hikashop_get('class.order');
$update = new stdClass();
$update->order_id = $order_id;
$update->order_status = 'shipped';

// Optionally add a history note and notify the customer
$update->history = new stdClass();
$update->history->history_notified = 1;
$update->history->history_reason = 'Your package has been picked up by the carrier.';

$orderClass->save($update);

To create a new product programmatically:

$product = new stdClass();
$product->product_name = 'API created product';
$product->product_code = 'PROD-001';
$product->categories = array(12, 15); // Category IDs

$productClass = hikashop_get('class.product');
$success = $productClass->save($product);

if ($success) {
    // These methods handle the related table updates (prices, categories, images)
    $productClass->updateCategories($product); // Saves to hikashop_product_category
    
    // Add a price
    $price = new stdClass();
    $price->price_value = 19.99;
    $price->price_currency_id = 1;
    $product->prices = array($price);
    $productClass->updatePrices($product);
}

Format a Price

Displays a price with the correct currency symbol and formatting based on HikaShop settings.

$currencyHelper = hikashop_get('helper.currency');
echo $currencyHelper->format(19.99, 1); // 19.99 is the value, 1 is the currency_id

Javascript events

On the Javascript side of things, Joomla doesn't have an event mechanism. So we actually implemented our own mechanism in HikaShop. To use it, you just need to add a few lines of code, like so:

if(window.Oby) {
	window.Oby.registerAjax(["cart.updated","wishlist.updated"],function(params){
		// ... your javascript code ...
	});
}

This will run your javascript code when either the cart is modified or the wishlist of the user is modified on the current page. So as you can see cart.updated and wishlist.updated are the name of the events and HikaShop offers a wide range of these events on the frontend of the website. Also, the params parameter usually contains important information relative to the current event. So we recommend you first do a call to console.log(params); to check what you're being given. Here is the list of events:

cart.updated

Triggered whenever the current cart is being changed from an add to cart button or the HikaShop cart module. params will contain:

  • params.type which will normally be "cart" for carts and "wishlist" for wishlists.
  • params.notify which is normally undefined if HikaShop wants the user to be notified of the modification or not. For an add to cart event, this will be true or undefined. But when a product is removed from the cart (via the cart module for example), this will be set to false by HikaShop.
  • params.resp will contain an object of the parsed json returned by the server after the AJAX request updating the cart. It can contain params.resp.product_name and params.resp.image if a product is being added to the cart. It can also contain params.resp.products with a list objects, one per product currently in the cart with their "quantity", "product_name" and "cart_product_id".
  • If you need extra information that HikaShop doesn't provide by default in params.resp, you can implement the onGetCartProductsInfo event of the Cart API in a plugin of the group "hikashop".

wishlist.updated

Triggered whenever the current wishlist is changed. Params are identical to cart.updated.

cart.empty

Triggered when the last product is removed from the cart. The system uses this to refresh the page or redirect based on settings.

checkout.step.completed

Triggered after an AJAX request completes a checkout step. The system uses this to transition to the next step.

hikashop.stateupdated

Triggered after a state selector is refreshed (e.g., after selecting a country). Params:

  • params.id: The ID of the container element.
  • params.elem: The actual <select> element.

checkout.user.updated

Triggered after user state changes (login, register, guest validation). Used to refresh address selection.

checkout.address.updated

Triggered after billing or shipping address changes.

checkout.cart.updated

Triggered after the cart is updated from the checkout cart view.

checkout.coupon.updated

Triggered after the coupon is updated (manually or via auto-load).

checkout.shipping.updated

Triggered when the available shipping methods list changes.

checkout.payment.updated

Triggered when the available payment methods list changes.

checkoutBlockRefresh

Triggered after a specific checkout view is refreshed. Params:

  • params.type: View name (address, cart, etc.).
  • params.cid: Step number.
  • params.pos: View position.

checkoutBlockSubmit

Triggered just before an AJAX request is made for a specific checkout block. You can use params.data to override the submitted data.

checkoutFormSubmit

Triggered just before the entire checkout form is submitted (e.g., clicking "Next" or "Finish").

compare.updated

Triggered when a product is added or removed from the comparison list.

quantity.checked

Triggered when a quantity input value changes. Params:

  • params.el: DOM element of the input.
  • params.value: New value.
  • params.max/params.min: Allowed limits.

hkContentChanged

Triggered after the product details page content changes (e.g., variant selection or option change).

hkAfterUpdateVariant

Triggered after a variant selection is processed. Params include params.selection (selected value IDs).

hkAfterProductListingSwitch

Triggered after switching between column and list views on a product listing.

filters.update

Triggered after filter data is sent to the server but before the UI is refreshed.

filters.updated

Triggered after the filters and product listing areas are updated.

order.placed

Triggered by the Order Notify plugin when a new order is received.