Developer documentation

Dear developer,

HikaShop runs on both Joomla and WordPress. Its plugin system is built on top of each CMS's native extension mechanism, allowing you to extend the shop's functionality with custom plugins.

HikaShop Developer Documentation

HikaShop provides a powerful plugin system. On Joomla, HikaShop plugins are standard Joomla plugins. On WordPress, they are WordPress plugins that register HikaShop event hooks.

HikaShop events are triggered when certain actions are performed (order creation, product deletion, etc.). To use these events, you need to create a 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 plugin. The group will be "hikashop" unless you create a payment or shipping plugin, in which case it will be "hikashoppayment" or "hikashopshipping" respectively.

On Joomla, HikaShop plugins are standard Joomla plugins. We recommend that you first learn how to create Joomla plugins: Joomla Plugin Development Documentation

On WordPress, HikaShop plugins are standard WordPress plugins. The HikaShop compatibility layer translates WordPress hooks into HikaShop events, so the same plugin code works on both platforms when you extend the hikashopPlugin class.

How to create a HikaShop plugin

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

The hikashopPlugin class provides a compatibility bridge across Joomla 3, 4, 5, 6 and WordPress, 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 and WordPress (where JRequest is deprecated and input handling 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

This event belongs to the payment plugin of the method the customer chose. It is documented with the other payment events, under the Payment API.

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.

 

onAfterOrderListing(&$rows, &$extrafields, $pageInfo)

Triggered once the order listing of your backend has loaded its orders, so that you can add your own column to it.

  • &$rows: The orders being displayed.
  • &$extrafields: The extra columns of the listing. Add yours to display it.
  • $pageInfo: The pagination, the filters and the sort order of the listing.

onBeforeModifyOrder(&$order, &$order_status, &$history, &$email)

Triggered when the status of an order is about to change, before anything is written. Change the status, the history entry it will record, or the email the customer receives.

  • &$order: The order, carrying the history entry about to be added.
  • &$order_status: The status the order will move to.
  • &$history: The history entry recording the change.
  • &$email: The email about to be sent, or false when none is.

onBeforeCreateRecurringSuborder($order_id, &$order)

Triggered before a new order is created for the next term of a subscription. Change the order about to be created, or its products, to make the renewal differ from the original.

  • $order_id: The order the subscription started from.
  • &$order: The renewal order about to be created.

onBeforeOrderExportQuery(&$filters, $paramBase)

Triggered when orders are exported from your backend, so that you can restrict what the export contains.

  • &$filters: The WHERE clauses of the export query.
  • $paramBase: The parameter prefix of the listing the export was started from.

onBeforeFrontendOrderListing($paramBase, &$pageInfo, &$filters, &$searchMap)

Triggered before the order history a customer sees on your website is loaded, so that you can change which orders it lists or what the search looks into.

  • $paramBase: The parameter prefix of the listing.
  • &$pageInfo: The pagination, the filters and the sort order.
  • &$filters: The WHERE clauses of the query.
  • &$searchMap: The columns the search box looks into.

onHikashopOrderTrackingDisplay($order)

Triggered on the thank you page displayed once an order is placed. It is where an analytics or conversion tracking plugin outputs its code, with the order available to it.

  • $order: The order that was just placed.

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.

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.

 

onAfterProductCharacteristicsLoad(&$product, &$mainCharacteristics, &$characteristics)

Triggered once the characteristics of a product have been loaded for the cart, so that you can change which ones are offered.

  • &$product: The product the characteristics belong to.
  • &$mainCharacteristics: The characteristics of the main product.
  • &$characteristics: The characteristics loaded.

onAfterVariantChecked(&$variant, &$element)

Triggered once a variant has been prepared for display, with its name built from its characteristics and its stock settled. Change the variant before it reaches the page.

  • &$variant: The variant, with its name and its quantity resolved.
  • &$element: The main product it belongs to.

onAfterVariantsCreation($product_id, $new_variants_ids, $element)

Triggered once HikaShop has generated the variants of a product from its characteristics, so that you can complete what it created.

  • $product_id: The main product.
  • $new_variants_ids: The ids of the variants just created.
  • $element: The main product object.

onHkContentParse(&$description, $description_type)

Triggered when the description of a product written in another syntax has to be turned into HTML. A plugin providing that syntax replaces the description with the HTML it produces.

  • &$description: The description to parse, replaced by the HTML.
  • $description_type: The syntax it is written in.

onHkContentParserLoad(&$plugin_values)

Triggered when HikaShop lists the syntaxes a description can be written in, HTML being the only one it provides. Register yours to have it offered on the product form.

  • &$plugin_values: The syntaxes, keyed by name, each giving its plugin and its editor.

onProductLayoutSelect(&$values)

Triggered when the layouts a product listing can use are listed. Add an entry to offer a layout of your own.

  • &$values: The layouts available, as an array of select options.

onBeforeProductStockUpdate(&$updates, $cancel)

Triggered before the stock and the sales counters of the products of an order are changed, whether the order is being placed or cancelled. Change the updates to decide what is written.

  • &$updates: The stock and sales changes about to be applied, per product.
  • $cancel: True when the order is being cancelled and the stock given back.

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, &$leftjoin)

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.
  • &$leftjoin: An array of LEFT JOIN clauses added to the query.

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, &$errors)

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.
  • &$errors: An array of error messages, to explain why no method was found.

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 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.

 

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_rates, &$cart)

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

  • &$usable_rates: An array of usable shipping rate objects.
  • &$cart: The cart object.

 

 

onShippingWarehouseFilter(&$shipping_groups, &$order, &$rates)

Triggered once the products of an order have been split into shipping groups, one per warehouse. Change the groups to decide what is shipped together and therefore how many shipping methods the customer is asked for.

  • &$shipping_groups: The groups of products, keyed by warehouse id.
  • &$order: The order object.
  • &$rates: The shipping rates available.

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).

 

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&notif_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.

 

onCheckPaymentOptions(&$paymentOptions, &$order)

Triggered when HikaShop asks what the payment of an order supports. A payment plugin sets the entries of $paymentOptions it can handle, and the backend then offers the matching buttons on the order.

  • &$paymentOptions: An array with the keys recurring, term and refund, each false by default.
  • &$order: The order object.

UCP (Universal Commerce Protocol)

The Universal Commerce Protocol (UCP) allows AI agents to discover, search, and purchase products on your store. HikaShop implements UCP through a system plugin that exposes REST API endpoints. Payment plugins can opt into UCP by implementing one or more of the following methods. All three are optional.

For a complete setup guide and flow diagrams, see the UCP tutorial. The Example Payment Plugin also contains documented implementations of all three methods.

Available methods for UCP support:

getPaymentURL(&$order, &$method)

Called by the UCP plugin when an AI agent completes a checkout without providing a payment token (hosted checkout flow). The method should create a hosted checkout session on the payment gateway and return the URL where the customer will be redirected to complete payment.

  • &$order: The HikaShop order object (with order_id, order_full_price, order_currency_id, etc.).
  • &$method: The payment method object with its parameters in payment_params.

Return value: A URL string on success, or false on failure. On failure, set $this->last_error with the error message.

Typically, you will also want to store the gateway's session/checkout ID in order_payment_params so that the onPaymentNotification method can look up the order when the gateway sends a webhook after the customer pays.

 

onUcpPaymentProcess(&$order, &$paymentContext, &$paymentResult)

Called by the UCP plugin when an AI agent completes a checkout with a payment token (e.g., a Google Pay token). The method should charge the token via the payment gateway's API.

  • &$order: The HikaShop order object.
  • &$paymentContext: An associative array containing:
    • 'credential': Array with 'token' (the encrypted payment token) and 'type'.
    • 'handler_id': The payment handler identifier (e.g., 'com.google.pay').
    • 'payment_instrument': Information about the payment instrument (card brand, last digits, etc.).
    • 'risk_signals': Optional risk assessment data from the AI platform.
  • &$paymentResult: An object to populate with the payment outcome:
    • success (bool): Whether the payment succeeded.
    • message (string): Error message on failure.
    • transaction_id (string): The gateway's transaction ID on success.
    • requires_redirect (bool): Set to true if a 3D Secure challenge is required.
    • continue_url (string): The 3DS challenge URL when requires_redirect is true.

Important: Always check that $order->order_payment_method === $this->name at the start and return early if it doesn't match, since all payment plugins receive this event.

 

getUcpGooglePayConfig()

Called by the UCP plugin during discovery (GET /.well-known/ucp) to detect whether this payment plugin supports Google Pay tokenization. The UCP plugin iterates over all published payment methods and calls this method on each one. The first non-null result is used.

Return value: An associative array with two keys, or null if not supported:

  • 'gateway': The gateway identifier as defined by Google Pay (e.g., 'stripe', 'worldline', 'adyen'). See the Google Pay gateway reference.
  • 'gatewayMerchantId': Your merchant identifier on the gateway (e.g., publishable key for Stripe, PSPID for Worldline).

The base class hikashopPaymentPlugin defines a default implementation that returns null. Override it in your plugin if your gateway supports Google Pay.

 

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

 

Nine events fire while getFullCart() assembles a cart, across three nested calls. Two of them repeat, once per product or once per variant, and one only fires when no payment method has been chosen yet. Click any event to jump to its description.

sequenceDiagram
    autonumber
    participant C as cart::getFullCart()
    participant G as cart::get()
    participant Q as checkCartQuantities()
    participant P as Your plugin

    C->>G: load the cart row
    G->>P: onBeforeCartLoad
    G->>P: onAfterCartLoad
    C->>P: onBeforeCartProductsLoad
    C->>Q: check the quantities
    Q->>P: onBeforeCheckCartQuantities
    loop each product
        Q->>P: onAfterProductQuantityCheck
    end
    Q->>P: onAfterCheckCartQuantities
    loop each variant
        C->>P: onAfterProductCharacteristicsLoad
    end
    C->>P: onAfterCartProductsLoad
    C->>P: onAfterCartCouponLoad
    C->>P: onAfterCartShippingLoad
    opt no payment method chosen yet
        C->>P: onHikaShopCartSelectPayment
    end
    C->>P: onAfterFullCartLoad

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.

 

 

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

Triggered when the cart has checked the quantities of its products against the stock and the limits, and before the products left without a quantity are removed from it. Change a quantity to overrule what HikaShop decided.

  • &$products: The products of the cart with the quantity each is allowed.
  • &$cart: The cart object.
  • $options: The options the check was run with.

onAfterCartRemoveAdditional(&$cart, $removeAdditional)

Triggered once an additional item a plugin had added to the cart has been removed by the customer, so that the plugin can clean up what it had stored with it.

  • &$cart: The cart the item was removed from.
  • $removeAdditional: The key of the item removed.

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

Triggered when the quantities of a cart have to be checked and its type is not one HikaShop handles itself, a type added by a plugin. Set $ret to false to refuse the cart.

  • &$cart: The cart being checked.
  • $parent_products: The main products of the variants in the cart.
  • &$ret: The result of the check. Set it to false to refuse the cart.

Checkout API

This API allows you to customize the HikaShop checkout workflow.

The checkout is not one sequence but two paths that alternate. The view renders every block of the current step, so the display events fire once per block, while the controller receives what the customer submitted and fires once per step. Click any event to jump to its description.

flowchart TB
    START(["Customer opens the checkout"]) --> INIT["onInitCheckoutStep"]
    INIT -->|"for the first block of the step"| R1

    R1["onBeforeCheckoutViewDisplay"] --> R2["the block renders"] --> R3["onAfterCheckoutViewDisplay"]
    R3 -.->|"a block with no view of its own uses this instead"| R4["onCheckoutStepDisplay"]
    R3 -->|"more blocks left in this step"| R1

    R3 --> WAIT{"The customer acts"}
    WAIT -->|"changes a block"| SUB["onAfterCheckoutStep"] --> BACK
    WAIT -->|"moves to the next step"| STEP["onAfterCheckoutStep"] --> EMPTY["onCheckoutEmptyContentCheck"] --> BACK
    BACK(["the step is rendered again"])

    WAIT -->|"places the order"| O1["onBeforeOrderCreate"]
    O1 --> O2["onAfterOrderCreate"] --> O3["onAfterOrderConfirm"]

The rendering events fire once for every block of the step, which is what the loop shows. onBeforeOrderCreate is where you refuse an order, by setting its $do to false. onAfterOrderConfirm belongs to the payment plugin of the method the customer chose.

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($controllerName, &$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.

onHikashopPopupList(&$plugins)

Triggered when HikaShop looks for the popup systems available, before displaying one. Register yours under the content or the image key to have it offered as a popup mode.

  • &$plugins: An array with a content and an image key, each listing the popup systems.

onHikashopPopupDisplay($popupMode, 'content', &$html, $text, $title, $url, $id, $params)

Triggered when a popup has to be displayed with a mode a plugin registered through onHikashopPopupList. Fill $html with your own markup; HikaShop falls back to its default popup when it stays empty.

  • $popupMode: The popup mode selected in the configuration.
  • 'content': The kind of popup, always content here.
  • &$html: The HTML of the popup. Fill it to take over the display.
  • $text: The text of the link opening the popup.
  • $title: The title of the popup.
  • $url: The address the popup loads.
  • $id: The id of the popup.
  • $params: The width, the height and the other options of the popup.

View 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)

Triggered before a view override is deleted.

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

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';
        }
    }
}

 

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 client ID (0 for frontend, 1 for administrator).

onHikashopMicrodataProductInfo(&$obj, &$element, $main)

Triggered on the product page after the JSON-LD structured data object is fully built (product info, offers, reviews, variants) but before it is encoded and injected into the page head. Use this event to modify the schema type, add properties, or enrich the structured data for specific product types (e.g. hotel rooms, event tickets).

  • &$obj: The JSON-LD object (stdClass). You can modify its properties, change $obj->{'@type'}, or add new schema.org properties.
  • &$element: The full product element (includes variants, images, etc.).
  • $main: The main product object (for variants, this is the parent product).

onHikashopMicrodataExtraObjects(&$extraObjects, &$element, $main)

Triggered on the product page after the main JSON-LD block has been injected. Use this event to add additional JSON-LD objects to the page (e.g. a separate LodgingBusiness or LocalBusiness block alongside the Product).

  • &$extraObjects: An array of stdClass objects. Each object you add will be encoded as a separate JSON-LD script block in the page head.
  • &$element: The full product element.
  • $main: The main product object.

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.

 

onSelectDiscount(&$product, &$discountsSelected, &$discounts, $zone_id, &$parent)

Triggered once HikaShop has sorted the discounts which apply to a product by priority, and before it keeps one. Reorder or change the selection to decide which discount wins.

  • &$product: The product the discount is being chosen for.
  • &$discountsSelected: The discounts kept, grouped by priority then by depth.
  • &$discounts: Every discount that was considered.
  • $zone_id: The zone the prices are computed for.
  • &$parent: The main product when the one above is a variant.

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.

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 CMS 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, &$externalOptions)

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.
  • &$externalOptions: An associative array of extra options for those fields.

onCustomfieldEdit(&$field, &$view)

Triggered when a custom field is opened for edition in your backend, so that a plugin providing its own field type can add what it needs to the form.

  • &$field: The custom field being edited.
  • &$view: The view displaying the form.

onTableFieldsLoad(&$externalValues)

Triggered when HikaShop builds the list of tables a custom field can be attached to. Add an entry to offer custom fields on a table of your own.

  • &$externalValues: The extra tables, as an array of select 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(&$orderstatus_columns, &$rows)

Triggered once the order status listing of your backend has been loaded, so that you can add your own column to it.

  • &$orderstatus_columns: The columns of the listing. Add yours to display it.
  • &$rows: The order status rows being displayed.

 

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.

onFilterTypeDisplay(&$allValues)

Triggered when the display types of a filter are listed in your backend. Add an entry to offer a filter type of your own next to the dropdown, the cursor and the others.

  • &$allValues: The display types, as an array of type key to label.

onInitFilterTypeClass($type)

Triggered when HikaShop needs the class of a filter type and cannot find it. Declare your class when $type is yours, so that the filter can be built.

  • $type: The filter type being loaded.

onFilterTypeConfig(&$element, &$plgHtml)

Triggered when the options of a filter are displayed in your backend. Append the configuration of your own filter type to $plgHtml, wrapped in an element carrying a data-plg-filter-type attribute, which is how the page shows it only for the selected type.

  • &$element: The filter being edited.
  • &$plgHtml: The HTML of the configuration. Append yours to it.

onFilterTypeSaveForm(&$filter, &$formData)

Triggered when a filter whose type or data source belongs to a plugin is saved, so that the plugin stores what its own configuration needs. HikaShop only raises it for types prefixed with "plg.".

  • &$filter: The filter being saved.
  • &$formData: The data posted by the form.

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.

onAfterTaxCreate(&$element)

Triggered after a tax rate is successfully created.

  • &$element: The created tax object.

onBeforeTaxUpdate(&$element, &$do)

Triggered before a tax rate is updated.

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

onAfterTaxUpdate(&$element)

Triggered after a tax rate is successfully updated.

  • &$element: The updated tax object.

onBeforeTaxDelete(&$ids, &$do)

Triggered before one or more tax rates are deleted.

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

onAfterTaxDelete(&$ids)

Triggered after one or more tax rates are successfully deleted.

  • &$ids: Array of deleted tax IDs.

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.

onAfterTaxationCreate(&$element)

Triggered after a taxation rule is successfully created.

  • &$element: The created taxation object.

onBeforeTaxationUpdate(&$element, &$do)

Triggered before a taxation rule is updated.

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

onAfterTaxationUpdate(&$element)

Triggered after a taxation rule is successfully updated.

  • &$element: The updated taxation object.

onBeforeTaxationDelete(&$ids, &$do)

Triggered before one or more taxation rules are deleted.

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

onAfterTaxationDelete(&$ids)

Triggered after one or more taxation rules are successfully deleted.

  • &$ids: Array of deleted taxation IDs.

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, $options)

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.
  • $options: An array of options for the download.

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, $ignoreFile)

Triggered before one or more files are deleted.

  • &$oldEntries: Array of file objects to be deleted.
  • $ignoreFile: True when only the records are removed and the files themselves are kept, so a plugin which stores them elsewhere should keep its copies too.

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.

onHikashopUploadStoreFile(&$file, &$file_path, $uploaded_file, $slice, $options)

Triggered while a file is being uploaded, after it has been validated but before HikaShop writes anything to the upload folder. It lets a plugin store the file somewhere else, for instance on a cloud storage. It is triggered for every kind of upload, images as well as product files, so a plugin must check $options['type'] and ignore what it does not handle. A plugin takes over the storage of a file by returning true: HikaShop then writes nothing itself and the plugin becomes responsible for the whole storage, including the assembling of a sliced upload.

  • &$file: The file being uploaded. A plugin which stores the file reports back on this object: partial set to true while more slices are expected, resume and slice to ask the browser to restart the upload at a given slice, error with a message on failure, and file_path and size once the file is complete. file_path is then recorded as the path of the file in place of the local name.
  • &$file_path: The name the file is stored under. It can be changed to store the file under a different name.
  • $uploaded_file: The temporary file of the slice being received.
  • $slice: The index, the total number, the size of the slices and the total size of the file, or null when the file is not uploaded in slices. Large files are sent by the browser in several requests, so a plugin is called once per slice and only the last one completes the file.
  • $options: The options of the upload, including type and the destination folder.

onHikashopFieldFileInfo(&$info, $value, $field)

Triggered when HikaShop needs the fingerprint and the size of a file of a custom field of the type "AJAX file" or "AJAX image" whose value starts with "@" or "#", which means it is stored by a plugin rather than on the server. It is triggered when the field is displayed and again when it is saved.

  • &$info: An object with hash and size, both empty. A plugin which recognises the value fills them in. hash takes the place of the checksum HikaShop computes for a file on the server: it is what proves that a value submitted with a form really is the file which was uploaded, so it must be something only the storage can give, and it must stay the same between the display and the save. A value left without a hash is refused when the form is saved.
  • $value: The value of the field, the reference of the file.
  • $field: The custom field the value belongs to.

onFieldFileDownload(&$found, $name, $field_table, $field_namekey, $options)

Triggered when a file uploaded through a custom field is requested and HikaShop could not match it to a record of its own. Set $found to true if the file belongs to something of yours and the customer may download it.

  • &$found: A boolean. Set it to true to allow the download.
  • $name: The name of the file requested.
  • $field_table: The table the custom field belongs to.
  • $field_namekey: The name key of the custom field.
  • $options: The options of the download.

onAfterDownloadFile(&$filename, &$file)

Triggered once a file has been sent to the customer, which is where a plugin records the download or applies its own counter.

  • &$filename: The path of the file that was sent.
  • &$file: The file object from the database.

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.

 

onMailTemplateListing(&$external_template_files, $mail_name)

Triggered when HikaShop lists the templates available for an email. Add your own file to offer a template that does not live in the HikaShop folders.

  • &$external_template_files: The extra templates, as an array of select options.
  • $mail_name: The email the templates are listed for.

onHkProcessMailTemplate(&$mail, &$data, &$content, &$vars, &$texts, &$templates)

Triggered while an email is being built from its template, with everything that goes into it. Change $content to produce the body yourself, or add to $vars and $texts to make more data available to the template.

  • &$mail: The email object.
  • &$data: The data the email is about, an order for instance.
  • &$content: The body produced so far.
  • &$vars: The variables the template can use.
  • &$texts: The texts the template can use.
  • &$templates: The templates being applied.

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.

 

onHikashopLanguageChange($locale)

Triggered once HikaShop has switched to another language and loaded its translation files, so that a plugin can load its own for the same language.

  • $locale: The language now in use, as its code, en-GB for instance.

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.

onBeforeMassactionProcess(&$massaction, &$elements, $report, &$do)

Triggered before a mass action runs, once the elements it will act on have been selected.

  • &$massaction: The mass action object.
  • &$elements: The elements the mass action will act on.
  • $report: The report of the mass action so far.
  • &$do: A boolean. Set it to false to stop the mass action before its actions run.

onAfterMassactionProcess(&$massaction, &$elements, $report)

Triggered once every action of the mass action has run.

  • &$massaction: The mass action object.
  • &$elements: The elements the mass action acted on.
  • $report: The report of the mass action.

onBeforeMassactionUpdate(&$element)

Triggered before a mass action is saved from your backend, so that a plugin can complete or correct what is about to be stored.

  • &$element: The mass action about to be saved.

onMassactionSpecialActions(&$special)

Triggered when HikaShop lists the mass actions considered dangerous, the ones only a Super User may configure or run. Declare yours here when it can reach outside the shop.

  • &$special: The names of the actions treated as special. Add yours to it.

onReloadPageMassActionAfterEdition(&$reload)

Triggered once a cell edited directly in a listing has been saved, to decide whether the page has to be reloaded rather than updated in place.

  • &$reload: A boolean. Set it to true to reload the whole page.

onSaveEditionSquareMassAction($data, $data_id, $table, $column, $value, $id, $type)

Triggered when a cell edited directly in a listing belongs to a plugin rather than to a HikaShop column, so that the plugin saves the value itself.

  • $data: The kind of data being edited.
  • $data_id: The id of that data.
  • $table: The table of the listing.
  • $column: The column being edited.
  • $value: The value entered.
  • $id: The record being edited.
  • $type: The type of the column.

onLoadResultMassActionAfterEdition($data, $data_id, $table, $column, $type, $id, $value, &$query)

Triggered after such a cell has been saved, to read back what should now be displayed in it.

  • $data: The kind of data being edited.
  • $data_id: The id of that data.
  • $table: The table of the listing.
  • $column: The column being edited.
  • $type: The type of the column.
  • $id: The record being edited.
  • $value: The value that was saved.
  • &$query: The query loading the value back.

onLoadDatatMassActionBeforeEdition($data, $data_id, $table, $column, $type, $ids, &$query, &$view)

Triggered before such a cell is opened for edition, to load the value and the choices it should offer.

  • $data: The kind of data being edited.
  • $data_id: The id of that data.
  • $table: The table of the listing.
  • $column: The column being edited.
  • $type: The type of the column.
  • $ids: The records being edited.
  • &$query: The query loading the current value.
  • &$view: The view displaying the listing.

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 CMS 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.

onNameboxTypesLoad(&$loaded_types)

Triggered when HikaShop loads the namebox types, the selectors used across the backend to pick a product, a category or a customer. Register a type of your own to be able to display it in your forms.

  • &$loaded_types: The namebox types, keyed by type name.

onHkContentParamsDisplay('menu', $name, &$element, &$extra_blocks)

Triggered when the parameters of a HikaShop menu item are displayed, so that a plugin can add its own settings to them. The blocks you add are displayed with the ones HikaShop provides.

  • 'menu': The kind of content, always menu here.
  • $name: The menu item type being edited.
  • &$element: The content type and the parameters currently set.
  • &$extra_blocks: An array with a products and a layouts key. Add your blocks to them.

onBeforeHikaPluginConfigurationListing($type, &$filters, &$order, &$searchMap, &$extrafilters, &$view)

Triggered before the listing of the payment, shipping or plugin configurations is loaded in your backend. Change the query, or add a filter of your own to the listing.

  • $type: The kind of listing: payment, shipping or plugin.
  • &$filters: The WHERE clauses of the query.
  • &$order: The ORDER BY clause of the query.
  • &$searchMap: The columns the search box looks into.
  • &$extrafilters: The extra filters displayed above the listing. Add yours to it.
  • &$view: The view displaying the listing.

onAfterHikaPluginConfigurationListing($type, &$rows, &$listing_columns, &$view)

Triggered once that listing has loaded its rows, so that you can add your own column to it.

  • $type: The kind of listing: payment, shipping or plugin.
  • &$rows: The methods being displayed.
  • &$listing_columns: The columns of the listing. Add yours to display it.
  • &$view: The view displaying the listing.

onHikaPluginConfiguration($type, &$plugin, &$element, &$extra_config, &$extra_blocks)

Triggered when the configuration of a payment or shipping method is displayed, so that a plugin can add settings of its own to the form of another plugin.

  • $type: The kind of method: payment, shipping or plugin.
  • &$plugin: The plugin whose configuration is displayed.
  • &$element: The method being configured.
  • &$extra_config: The extra settings. Add yours to it.
  • &$extra_blocks: The extra blocks displayed around the settings.

onBeforeCharacteristicListing($paramBase, &$extrafilters, &$pageInfo, &$filters)

Triggered before the characteristic listing of your backend is loaded, so that you can add a filter of your own or change the query.

  • $paramBase: The parameter prefix of the listing.
  • &$extrafilters: The extra filters displayed above the listing.
  • &$pageInfo: The pagination, the filters and the sort order.
  • &$filters: The WHERE clauses of the query.

onNameboxCharacteristicsLoad($typeConfig, &$fullLoad, $mode, $value, $search, $options, &$ret)

Triggered when a characteristic selector is filled and the values do not come from HikaShop itself, so that a plugin can supply them.

  • $typeConfig: The configuration of the selector.
  • &$fullLoad: Whether every value is being loaded or only a search.
  • $mode: The mode of the selector.
  • $value: The value currently selected.
  • $search: What the user typed.
  • $options: The options of the selector.
  • &$ret: The values to display. Fill it to supply your own.

onUploadControllerGet($controllerName, &$controller)

Triggered when an upload is handled and HikaShop does not recognise the controller it is for. Set $controller to your own to take the upload over.

  • $controllerName: The controller the upload was sent to.
  • &$controller: The controller that will handle it. Set yours to take over.

onAfterHikaPluginConfigurationSelectionListing($type, &$plugins, &$view)

Triggered when the list of payment or shipping plugins you can add a method for is displayed, so that you can add an entry of your own to it.

  • $type: The kind of listing: payment, shipping or plugin.
  • &$plugins: The plugins offered. Add yours to it.
  • &$view: The view displaying the listing.

onBeforeHikaPluginCreate($type, &$element, &$do)

Triggered before a payment or shipping method is created. Set $do to false to refuse the creation.

  • $type: The kind of method: payment or shipping.
  • &$element: The method about to be created.
  • &$do: A boolean. Set it to false to cancel the creation.

onBeforeHikaPluginUpdate($type, &$element, &$do)

Triggered before a payment or shipping method is saved. Set $do to false to refuse the change.

  • $type: The kind of method: payment or shipping.
  • &$element: The method about to be saved.
  • &$do: A boolean. Set it to false to cancel the update.

onAfterProductsImport(&$view, &$importProducts)

Triggered once a product import has finished, with everything it created or changed, which is where a plugin applies what it needs to the imported products.

  • &$view: The import view, carrying its report.
  • &$importProducts: The products that were imported.

onGetImportSupportedColumns(&$columns)

Triggered when the import lists the columns it understands. Add yours so that a file carrying them can be matched to your own data.

  • &$columns: The columns the import supports. Add yours to it.

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 cross-platform compatibility, use HikaShop's asset loading functions. For platform-specific asset loading:

On Joomla (J4+), use the Web Asset Manager:

if (defined('JVERSION') && version_compare(JVERSION, '4.0', '>=')) {
    $wa = JFactory::getDocument()->getWebAssetManager();
    $wa->registerAndUseStyle('plg_yourplugin.style', 'plugins/hikashop/yourplugin/style.css');
    $wa->registerAndUseScript('plg_yourplugin.script', 'plugins/hikashop/yourplugin/script.js', [], ['defer' => true], ['jquery']);
} elseif (defined('ABSPATH')) {
    // WordPress
    wp_enqueue_style('plg_yourplugin_style', plugins_url('yourplugin/style.css', __FILE__));
    wp_enqueue_script('plg_yourplugin_script', plugins_url('yourplugin/script.js', __FILE__), array('jquery'), false, true);
} 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 or the WordPress Plugin Developer 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 on Joomla: templates/YOUR_TEMPLATE/html/com_hikashop/VIEW_GROUP/VIEW_NAME.php
For example, to override the product page: templates/cassiopeia/html/com_hikashop/product/show.php

Manual Override Path on WordPress: wp-content/themes/YOUR_THEME/hikashop/VIEW_GROUP/VIEW_NAME.php
For example: wp-content/themes/flavor/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:
Joomla: templates/YOUR_TEMPLATE/html/com_hikashop/PLUGIN_NAME/somepage.php
WordPress: wp-content/themes/YOUR_THEME/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/theme folder and appending Override to the class name.

Joomla path: templates/YOUR_TEMPLATE/html/com_hikashop/administrator/XXXX/yyy.override.php
WordPress path: wp-content/themes/YOUR_THEME/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 CMS database prefix (e.g. jos_ on Joomla, wp_ on WordPress) 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 CMS users (Joomla or WordPress), 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.

How the main tables reference each other. HikaShop declares no foreign keys, so these are the conventions the code follows, not constraints the database enforces. It is drawn in three parts rather than one, because a single graph of every relation came out too wide to read.

Products, categories and variants

erDiagram
    hikashop_category ||--o{ hikashop_product_category : "category_id"
    hikashop_product ||--o{ hikashop_product_category : "product_id"
    hikashop_product ||--o{ hikashop_variant : "variant_product_id"
    hikashop_characteristic ||--o{ hikashop_variant : "variant_characteristic_id"

Three of these tables also point at themselves, which the diagram leaves out because the label has nowhere to sit: a category has a category_parent_id, a characteristic has a characteristic_parent_id, and a variant is a product whose product_parent_id points at the main one. The hikashop_variant rows say which characteristic values that variant stands for.

Prices, taxes and what hangs off a product

erDiagram
    hikashop_currency ||--o{ hikashop_price : "price_currency_id"
    hikashop_product ||--o{ hikashop_price : "price_product_id"
    hikashop_category ||--o{ hikashop_product : "product_tax_id"
    hikashop_category ||--o{ hikashop_taxation : "category_namekey"
    hikashop_tax ||--o{ hikashop_taxation : "tax_namekey"
    hikashop_zone ||--o{ hikashop_taxation : "zone_namekey"
    hikashop_zone ||--o{ hikashop_zone_link : "zone_parent_namekey"
    hikashop_product ||--o{ hikashop_file : "file_ref_id"
    hikashop_product ||--o{ hikashop_vote : "vote_ref_id"
    hikashop_product ||--o{ hikashop_waitlist : "waitlist_product_id"

The tax of a product is not a column but a category: product_tax_id names a category of the tax type, and getTax() joins that category to hikashop_taxation on category_namekey to find the rate for the customer zone. When no rule matches it walks up category_parent_id and tries again. hikashop_file and hikashop_vote are shared tables: their file_type and vote_ref_type say what the row belongs to, a product among others.

Customers, carts and orders

erDiagram
    hikashop_user ||--o{ hikashop_address : "address_user_id"
    hikashop_user ||--o{ hikashop_cart : "user_id"
    hikashop_user ||--o{ hikashop_order : "order_user_id"
    hikashop_address ||--o{ hikashop_order : "billing and shipping"
    hikashop_cart ||--o{ hikashop_cart_product : "cart_id"
    hikashop_product ||--o{ hikashop_cart_product : "product_id"
    hikashop_order ||--o{ hikashop_order_product : "order_id"
    hikashop_product ||--o{ hikashop_order_product : "product_id"
    hikashop_order ||--o{ hikashop_history : "history_order_id"
    hikashop_currency ||--o{ hikashop_order : "order_currency_id"

An order also points at another order through order_parent_id, which is how the terms of a subscription are linked to the one that started them. Every table above is listed with its purpose in the section just before. Scroll a diagram sideways if your screen cuts it off.

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_user_id = 42;
$order->order_status = 'created';
$order->order_currency_id = 1; // ID from hikashop_currency
$order->order_full_price = 120.50;

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

// Important: Products must be assigned to $order->cart->products
$order->cart = new stdClass();
$order->cart->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, we implemented our own event 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.

vote.beforeListRefresh

Triggered right after a comment / vote is saved on the product page, before the front-end tries to refresh the comment listing area. This lets a product display layout that conditionally renders the comment listing wrapper (for example the show_tabular layout, which hides the Comments tab when the product has no comments yet) inject that wrapper on the fly so the newly posted comment can be shown without a full page reload. The handler should make sure an element with id hikashop_vote_listing (or hikashop_product_vote_listing) is present in the DOM, the front-end then sets its innerHTML with the refreshed listing returned by the server. If no handler creates the container, the front-end falls back to a full page reload so the comment is still visible.

Params:

  • params.ref_id: the reviewed item id (the product id for a product comment).
  • params.type: the vote type, normally "product".