CartThrob 9 documentation for ExpressionEngine commerce teams Visit CartThrob.com
Add-on docs
CartThrob.com

CartThrob Fees Version 4.0.1

Overview

CartThrob Fees adds automatic fee line items to the cart based on cart/customer context and fee rules defined in the control panel.

In current released code, fee rules can target:

  • any cart (AUTO)
  • per item
  • item option matches (each, once, once per product)
  • custom cart data key/value
  • customer info fields (including gateway)

Fee line items are written as cart items with:

  • entry_id = null
  • title = fee name
  • price = computed fee total
  • quantity = fee quantity
  • no_shipping = true

Requirements

  • ExpressionEngine 6.0+
  • CartThrob 6.1+
  • PHP 7.1+ (composer.json)

Installation

  1. Upload /cartthrob_fees/ to /system/user/addons/.
  2. Install CartThrob Fees from the Add-ons page.
  3. Open Add-ons > CartThrob Fees and create fee rows.
  4. Save and run a cart test to confirm matching rules apply.

Upgrading

  1. Upload the new add-on files, replacing the existing cartthrob_fees folder.
  2. Run add-on updates from the Add-ons page.
  3. Re-open CartThrob Fees settings and verify all fee rows.

Upgrading From Versions Prior To 3.0.0

Version 3.0.0 introduced schema/model changes:

  1. cartthrob_fees_settings gained primary key id.
  2. Legacy serialized flag handling in settings was removed in favor of native serialized handling.
  3. Legacy cartthrob_fees_table was replaced with cartthrob_fees.
  4. Fee records are stored as rows (not serialized fee bundles).
  5. get_fees outputs both formatted and numeric fee values via :numeric variables.

Start Here (10-Minute Setup)

  1. Go to Add-ons > CartThrob Fees.
  2. Add one row with:

- Fee Name: Handling Fee - Price: 4.95 - Percent: leave blank - Apply Field: AUTO - Key: leave blank - Match Value: GLOBAL - Are fees taxable?: No (or Yes if needed) 3. Save. 4. Add an item to cart and output: - {exp:cartthrob_fees:fees_total} - {exp:cartthrob_fees:get_fees}...{/exp:cartthrob_fees:get_fees} 5. Confirm fee appears in cart totals and fee loop output.

Common Tasks With Examples

1. Add A Flat Fee For Every Cart

  • Use field = AUTO
  • Set price (leave percent empty)
  • Use value = GLOBAL

2. Add A Percentage-Based Fee

  • Use field = AUTO (or a conditional field)
  • Set percent (leave price empty)
  • Fee is calculated from subtotal before fees

3. Add Item Option Fees

  • item_options_key_each: evaluates matching items and applies per matching item pass
  • item_options_key_once: applies once for a given key/value match set
  • item_options_key_once_per_product: applies once per unique product (entry_id)

4. Add Customer-Context Fees

Use customer info fields like country_code, state, email_address, gateway, etc., with value set to either a specific match or GLOBAL.

Control Panel Reference

Primary route: addons/settings/cartthrob_fees

Main Screen

Screen content is one editable grid of fee rows.

Save behavior in current code:

  • Save clears all existing fee rows for current site
  • then inserts all submitted rows from the grid
  • row reorder is disabled in the grid config

Settings Grid Columns

  1. Fee Name (name)

- Label/name for the fee line item.

  1. Price (price)

- Flat fee amount. - If both price and percent are provided, code paths prioritize price.

  1. Percent of subtotal (percent)

- Percent-based fee amount used when price is empty.

  1. Apply fee when customer info equals match value (field)

- Selects the rule type and customer/item context to match.

  1. (or) Apply fee when this custom_data/item_options key equals match value (key)

- Used by custom-data and item-option fee types.

  1. match value (use GLOBAL to match any) (value)

- Matching value for selected rule. - New row default is GLOBAL.

  1. Are fees taxable? (taxable)

- Yes/No toggle for tax treatment.

Apply Field Values

Current field dropdown options in code:

  • AUTO (Any Field)
  • per_item
  • item_options_key_each
  • item_options_key_once
  • item_options_key_once_per_product
  • custom_data_key
  • Customer fields: address, address2, card_type, city, company, country_code, currency_code, description, email_address, first_name, gateway, group_id, ip_address, language, last_name, phone, region, screen_name, state, shipping_address, shipping_address2, shipping_city, shipping_company, shipping_country_code, shipping_first_name, shipping_last_name, shipping_option, shipping_state, shipping_zip, use_billing_info, username, zip

Utilities > Install

Route: addons/settings/cartthrob_fees/install

Purpose:

  • installs bundled template groups/templates from installer/templates/

Behavior:

  • choose template groups via checkbox list
  • submit to do_installation
  • success/failure alerts are shown inline

How Fees Are Calculated

Runtime Hooks

Extension hooks include:

  • cartthrob_add_to_cart_start
  • cartthrob_save_customer_info_end
  • cartthrob_update_cart_end
  • cartthrob_delete_from_cart_end
  • cartthrob_pre_process
  • cartthrob_calculate_total

Processing Flow

  1. Existing fee meta and previously-added fee line items are cleared.
  2. Fee rows are loaded from cartthrob_fees table for current site_id.
  3. Matching fee strategy object is created from each row.
  4. Fee value is calculated from either subtotal or item list, depending on type.
  5. Matching fee objects are stored in cart meta cartthrob_fees.
  6. Fee line items are added back into cart.

Template Tags

This add-on exposes tags via both patterns:

  • module form: {exp:cartthrob_fees:...}
  • CartThrob addon registration form: {exp:cartthrob:...}

get_fees

Tag pair that loops through active fees currently applied to cart.

Examples:

{exp:cartthrob_fees:get_fees}
  {fee_name}: {fee_total}
{/exp:cartthrob_fees:get_fees}

{exp:cartthrob:get_fees}
  {fee_name}: {fee_total}
{/exp:cartthrob:get_fees}

Parameters:

  • none in current implementation

Pair variables (from code):

  • {fee_name}
  • {fee_price} (formatted)
  • {fee_price:numeric} (raw numeric)
  • {fee_percent}
  • {field_name}
  • {custom_data_key}
  • {custom_data}
  • {taxable}
  • {fee_total} (formatted)
  • {fee_total:numeric} (raw numeric)
  • {item_price} (item-based fee types)
  • {quantity} (item-based fee types)

Conditional:

  • {if no_results}...{/if}

fees_total

Outputs total of all active fees in cart.

Examples:

{exp:cartthrob_fees:fees_total}

{exp:cartthrob_fees:fees_total:numeric}

Parameters:

  • no named parameters
  • optional tag segment suffix :numeric returns unformatted raw number

Changelog

Version 4.0.1

Release January 18, 2022

  • FIXED: Control panel fee update notification was deferred and not displaying on save.
  • FIXED: Item Option fees incorrectly creating empty fees when item option did not match.

Version 4.0.0

Release January 11, 2022

  • ADDED: New “Item Options (once per product)” fee type.
  • ADDED: ExpressionEngine 6+, CartThrob 6+ support.

Version 3.0.0

Release December 13, 2021

  • ADDED: CartThrob 5+ support.

Version 2.0.1

Release June 06, 2019

  • FIXED: Per Item Fee where fee was not applied per item.

Version 2.0.0

Release March 11, 2019

  • ADDED: CartThrob 4+ support.