Custom Fees for Magento 2

by Joseph Leedy

Custom Fees allows merchants to configure additional fees to be charged to
customers when orders are placed.

Features

• Allows fees to be configured with a label and amount to be added to an order
  • Custom fees configuration can be imported via a CSV spreadsheet
  • Conditions can be defined to determine whether a custom fee should be
    applied to an order based on product and cart details, including
    specific product attributes, product SKU, cart subtotal, cart item count,
    total cart weight and more
  • Custom fees can be applied as a fixed amount or a percentage of the order
    subtotal
• Custom fees are displayed for orders, invoices and credit memos in both the
  frontend and backend
• Custom fees can be charged and displayed including or excluding tax
• Custom fees can be refunded via Magento's credit memo functionality
• Discounts can be applied to custom fees using Cart Price Rules
• Includes a report detailing all charged custom fees for a given time period
• Fully compatible with the Hyvä theme (Hyvä Default, Hyvä CSP, Hyvä Checkout
  and Hyvä Checkout CSP)

Requirements

• PHP 8.1 or greater
• Magento Open Source 2.4.4 or greater, Adobe Commerce 2.4.4 or greater, or
  Mage-OS 1.0 or greater*
• MySQL 8.0.4 or greater, MariaDB 10.6.0 or greater, or a MySQL 8-compatible
  database server (for generating reports)

Note: Mage-OS compatibility has not been tested, but it
is functionally equivalent to Magento Open Source 2.4.6 or greater.

Installation

This extension can be installed via Composer from Packagist by running
these commands from a terminal on a Web server or in the desired installation
location:

cd /path/to/your/store
composer require joseph-leedy/module-custom-fees
php bin/magento module:enable JosephLeedy_CustomFees
php bin/magento setup:upgrade
php bin/magento setup:di:compile
php bin/magento setup:static-content:deploy

Updating

This extension can be updated via Composer from Packagist by running
these commands from a terminal on a Web server or in the desired installation
location:

cd /path/to/your/store
composer update joseph-leedy/module-custom-fees
php bin/magento setup:upgrade
php bin/magento setup:di:compile
php bin/magento setup:static-content:deploy

Usage

Configuration

Custom Fees

Custom Fees can be added from the Magento Admin panel by going to Stores > Settings > Configuration > Sales > Sales > Custom Order Fees. The overall
display order of the Custom Fees block in relation to other totals shown in the
cart and checkout can be configured at Stores > Settings > Configuration > Sales > Sales > Checkout Totals Sort Order. All settings for this extension
can be configured in the Global (Default), Website or Store scope.

Report Aggregation

Report aggregation can be configured at Stores > Settings > Configuration > General > Reports > Custom Order Fees Report.

Taxes

Taxes can be configured at Stores > Settings > Configuration > Sales > Tax.

Available Settings

Importing Custom Fees

The Custom Fees configuration page allows fees to imported from a CSV
spreadsheet containing the following columns:

Example CSV Import Spreadsheet

code,title,type,status,show_percentage,value
example_fee,"Example Fee",fixed,enabled,0,5.00

Configuring Adavanced Settings

Additional settings for a Custom Fee, including Conditions, can be found in the
Advanced Settings dialog by clicking on the cog icon "⚙️."

Reporting

To view a report of the collected custom order fees, go to Reports > Sales > Custom Order Fees in the Magento Admin panel.

Note: For performance reasons, the report generation process makes use of
special database functions that are only available in MySQL 8.0.4+ or
MariaDB 10.6.0+. Errors or unexpected behavior may occur when using incompatible
database server software versions.

Applying Discounts to Custom Fees

To apply a discount to a custom fee, go to Marketing > Promotions > Cart Price Rules in the Magento Admin panel and follow these instructions:

1. Click on "Add New Rule" or select an existing rule
2. Expand the "Actions" section and click on the "Apply to Custom Fee Amount"
   toggle

Note: To apply a discount to a specific custom fee, add an action
condition by following these instructions:

1. In the "Actions" section, under the "Apply the rule only to cart items
   matching the following conditions..." heading, click on the green plus icon
2. Select "Custom Fee" from the condition dropdown
3. Click on the ellipses button and choose the desired custom fee from the list

Support

If you experience any issues or errors while using this extension, please
open an issue in the GitHub repository. Be sure to include all relevant
information, including a description of the issue or error, what you were doing
when it occurred, what versions of Magento Open Source or Adobe Commerce and PHP
are installed and any other pertinent details. I will do my best to respond to
your request in a timely manner.

License

The source code contained in this extension is licensed under the Open Software
License version 3.0 (OSL-3.0) license. A copy of this license can be found in
the LICENSE file included with the source code or online at
https://opensource.org/licenses/OSL-3.0.

Copyright for the included source code is exclusively held by Joseph Leedy,
all rights reserved.

History

A full history of the extension can be found in the CHANGELOG.md file.

Contributing

We welcome and value your contribution. For more details on how you can help us
improve and maintain this tool, please see the CONTRIBUTING.md file.

Shout-Outs

Contributors

These wonderful people have helped this extension become what it is today, and
I am truly grateful to them for their contributions:

• A huge thanks to @pykettk, @Vinai and @hostep for reviewing the Hyvä
  compatibility implementation in pull request #16 and suggesting improvements!️

Supporters

I owe the following fine folks a debt of gratitude for their continuing
support:

• @paulcdejean

Changelog for Custom Fees for Magento 2 by Joseph Leedy

All notable changes to this extension will be documented in this file.

The format is based on Keep a Changelog, and this extension adheres to
Semantic Versioning.

For more information about this extension, please refer to the README
document.

Unreleased

1.5.0

Added

• A product attribute that can be used to determine whether or not a custom fee
  should be applied to an order is now created automatically when the extension
  is installed
• Data for the Custom Order Fees Report can now be aggregated automatically on
  a chosen schedule
• Custom fees can now be charged with tax and displayed inclusive or exclusive
  of tax
• Cart Price Rules can now be used to apply discounts to custom fees for
  orders, invoices and credit memos

Changed

• Ordered custom fees are now indexed by their corresponding fee code
• Data for ordered, invoiced and refunded custom fees is now represented by
  models with corresponding interfaces instead of arrays
• Usages of the mixed[] type for extension attributes have been replaced with
  the new interfaces for ordered, invoiced and refunded custom fees
• All total models, blocks and other logic now use the new interfaces and models

Removed

• The data patch used to add missing fields to the existing custom order fees
  data has been removed
• The plug-in used to temporarily store the refunded custom fee amounts entered
  in the Admin panel during credit memo creation has been removed

1.4.0

• This version was skipped due to an issue with creating the tag for it

1.3.2

Fixed

• Missing return type annotations have been added to the Custom Order Fees
  Interface
• Incorrect sales orders were included in packing slips printed from the
  Magento Admin panel (caused by the plug-in used to join custom order fees
  with sales orders in the Admin Sales Order Grid)

1.3.1

Changed

• Totals in the Custom Order Fees Report are now sorted by order currency

Fixed

• Custom fee totals were rendered for the related order instead of the
  invoice or credit memo on sales PDF files printed from the Magento Admin panel

1.3.0

Added

• Custom fees can be enabled or disabled
• Custom fees can be refunded from credit memos without requiring an adjustment
  fee (the previous work-around was to create an adjustment fee of the same
  amount as the custom fee)

Changed

• Renamed the custom_fees column in the custom_order_fees table to clarify
  its purpose (new name: custom_fees_ordered)
• The custom_order_fees table now includes a column called
  custom_fees_refunded to track the total amount of custom fees refunded for
  each credit memo related to the order
• The Custom Order Fees Report now includes a column for the total amount of
  custom fees refunded for each order, aggregated from the new
  custom_fees_refunded column in the custom_order_fees table
• The custom_order_fees table now includes a column called
  custom_fees_invoiced to track the total amount of custom fees invoiced for
  each invoice related to the order

Deprecated

• The method retrieve() in the CustomFeesRetriever service has been
  deprecated in favor of the retrieveOrderedCustomFees() method

1.2.3

Fixed

• An exception was thrown when loading the Sales Order Grid in the Admin panel
  if the JSON data in the custom_order_fees table was quoted

1.2.2

Fixed

• The Custom Order Fees Report did not aggregate custom fees if the custom
  order fee data was quoted in the database
• The Custom Order Fees Report did not aggregate custom fees if the related
  orders had multiple invoices

Changed

• Regenerated the database schema allowlist to add missing constraints for the
  custom_order_fees table

1.2.1

Fixed

• Custom fees were not calculated correctly when calculating totals for
  orders with multiple invoices
• Custom fees were not calculated correctly when calculating totals for
  orders with multiple credit memos

1.2.0

Added

• Configuration for custom fees can be imported from a CSV spreadsheet
• Conditions can be defined in the extension configuration to determine whether
  or not to apply a custom fee to an order
• Custom Fees can be calculated as a percentage of an order's subtotal

1.1.1

Fixed

• Softened dependency on Zend Framework 1 Database component to fix
  incompatibility with Magento 2.4.4 and 2.4.5

1.1.0

Added

• Custom fees are now rendered in columns in the Sales Order Grid in the Admin
  panel
• A report summarizing the total amount of collected custom order fees can be
  generated from the Admin panel
• Custom fees are now rendered on the Cart page in the Hyvä frontend
• Custom fees are now rendered on the Checkout pages in the Hyvä frontend

Fixed

• Reorded custom fees totals to be placed after tax totals on customer and
  guest order, invoice and credit memo pages in Hyvä frontend

1.0.2

Fixed

• Mark constructor parameters as explicitly nullable in custom order fees model
  to fix deprecation errors thrown by PHP 8.4

Changed

• Moved the Custom Fees configuration field to be placed after the Tax
  field in the Totals Sort Order group

1.0.1

Fixed

• Narrowed type for custom_fees Cart extension attribute to fix Swagger error
• Added and updated method annotations in Custom Order Fees Interface to fix
  Swagger errors

1.0.0

Added

• Initial version of extension