User Guide | Setting Discount Session Data

Data is set to the cart session by using functions primarily from flexi carts standard library.

The data that can be set in the cart session includes data of items added to the cart, user localisation data and cart configuration settings.

Since many of flexi carts features can be set using either manually submitted data, or data retrieved from the database; there are often two versions of a function to set session data. Functions that update session data using the database are prefixed with the function name 'update_xxx', whilst functions that use manually set data are prefixed with the name 'set_xxx'.

Set Discount Session Data

Discount Function Index | Discount Config | Get Discount Session Data | Get Discount Helper Data | Discount Admin Data
Set Discount Data to Session

set_discount() | set_discount_codes() | update_discount_codes()

Unset Session Discount Data

unset_discount() | unset_excluded_discounts()

Help with Setting Session Data Functions

Show / Hide Help

Name: The name of the function (method).

Data Type: The data type that is expected by the function.

  • bool : Requires a boolean value of 'TRUE' or 'FALSE'.
  • string : Requires a textual value.
  • int : Requires a numeric value. It does not matter whether the value is an integer, float, decimal etc.
  • array : Requires an array.

Required: Defines whether the parameter requires a value to be submitted.

Default: Defines the default parameter value that is used if no other value is submitted.

set_discount()

Manually set or update a discount against a summary column total, discounting either a fixed rate or percentage off of the summary value.
Setting discounts manually does not require the use of any database tables.


Library and Requirements

Available via the standard library only.

Does not require any database tables to be enabled.

Function Parameters
set_discount(discount_data, recalculate_cart) Help
Name Data Type Required Default Description
discount_data array Yes FALSE The array contains the discount data that is to update the carts discount data.
See the notes and examples below for further information.
recalculate_cart bool No TRUE Define if all cart totals must be recalculated on success, regardless of whether the function has determined to do so or not.
The purpose of this is prevent multiple unnecessary recalculations of the cart if this function is used with other cart updating functions.
How it Works

The function loops through the 'discount_data' array and sets any data from the following array keys to the cart discount data.

The valid array keys are 'id', 'description', 'value', 'column', 'calculation', 'tax_method' and 'void_reward_points'.

  • 'id' - The id to reference the discount by if updating or deleting it.
  • 'description' - The description of the discount.
  • 'value' - The value of the discount. Submitted values must be numeric.
  • 'column' - Defines the cart summary column to apply the discount to.
    Valid column names are 'item_summary_total' - the carts item summary total, 'shipping_total' - the carts shipping total, 'total' - the carts summary total.
    If no value or an invalid value is set, it will default to the carts total summary column.
  • 'calculation' - Defines the type of discount that should be applied.
    Valid calculation method values are '1' - percentage rate discount, '2' - flat rate discount, '3' - new value discount.
    If no value or an invalid value is set, it will default to a percentage rate discount.
    'New value' discounts can only be applied to the carts shipping total.
  • 'tax_method' - Defines how tax should be calculated on the discount value.
    Valid tax method values are '1' - apply tax before discount, '2' - apply discount before tax, '3' - apply discount before tax, then add original tax value.
    If no value or an invalid value is set, it will default to a the carts default tax method.
  • 'void_reward_points' - A boolean value defining whether applying the discount should void the customer from earning any reward points from the purchase.
    If no value is set, reward points will not be voided.
Notes

As well as setting new discounts, this function can be used to update an existing discount too. When updating a discount, simply include the id of the to-be-updated discount in the 'discount_data' array. The other data in the array will then be used to update the discount.


Only one discount can be applied to each cart summary column.
No item discounts can be manually set as this is managed by the database discount tables.


This function can also be set via the 'update_cart()' function.

Return Values

Failure:FALSE | An error message will be set.

Success:TRUE | A status message will be set.

Example
$discount_data = array(
'id' => 'example_id',
'description' => 'Example Description',
'value' => 10,
'column' => 'total',
'calculation' => '1', // Percentage rate discount
'tax_method' => FALSE, // Carts default tax method
'void_reward_points' => TRUE // Void any reward points being earnt
);

$this->flexi_cart->set_discount($discount_data);

set_discount_codes()

Applies discount codes to the cart discount data, whether they can be activated or not.


Library and Requirements

Available via the standard library only.

Requires the discount database tables to be enabled.

Function Parameters
set_discount_codes(discount_codes, recalculate_cart) Help
Name Data Type Required Default Description
discount_codes string | int | array Yes FALSE Can be either a string, int, or an array of values, that the function will attempt to match against discount codes within the discount table.
recalculate_cart bool No TRUE Define if all cart totals must be recalculated on success, regardless of whether the function has determined to do so or not.
The purpose of this is prevent multiple unnecessary recalculations of the cart if this function is used with other cart updating functions.
How it Works

The function validates that the codes in the 'discount_codes' data are valid discounts.
All codes that are active are then applied to the cart session data.

Notes

This function differs from 'update_discount_codes()' as it only sets new codes, it does not remove any codes from the cart that do not exist in the submitted data.

Return Values

Failure:FALSE | An error message will be set.

Success:TRUE | A status message will be set.

Example
// Example #1 : Update the discount codes using a string or int.

$discount_code = 'EXAMPLE-CODE';

$this->flexi_cart->set_discount_codes($discount_code);
// Example #2 : Update the discount codes using an array.

$discount_codes = array(
'EXAMPLE-CODE-1',
'EXAMPLE-CODE-2'
);

$this->flexi_cart->set_discount_codes($discount_codes);

update_discount_codes()

Updates discounts in the cart, removing any existing discounts that are not in the submitted data, and adding any valid new ones.


Library and Requirements

Available via the standard library only.

Requires the discount database tables to be enabled.

Function Parameters
update_discount_codes(discount_codes, recalculate_cart) Help
Name Data Type Required Default Description
discount_codes string | int | array Yes FALSE Can be either a string, int, or an array of values, that the function will attempt to match against discount codes within the discount table.
recalculate_cart bool No TRUE Define if all cart totals must be recalculated on success, regardless of whether the function has determined to do so or not.
The purpose of this is prevent multiple unnecessary recalculations of the cart if this function is used with other cart updating functions.
How it Works

The function loops through all existing discount codes that are applied to the cart, if the discount code is not in the submitted 'discount_codes' data, then it is unset from the cart session data.

The function then validates that the codes in the 'discount_codes' data are valid discounts.
All codes that are active are then applied to the cart session data.

Notes

This function differs from 'set_discount_codes()' as it sets new codes AND also removes any codes from the cart that do not exist in the submitted data.

Return Values

Failure:FALSE | An error message will be set..

Success:TRUE | A status message will be set.

Example
// Example #1 : Update the discount codes using a string or int.

$discount_code = 'EXAMPLE-CODE';

$this->flexi_cart->update_discount_codes($discount_code);
// Example #2 : Update the discount codes using an array.

$discount_codes = array(
'EXAMPLE-CODE-1',
'EXAMPLE-CODE-2'
);

$this->flexi_cart->update_discount_codes($discount_codes);

unset_discount()

Remove any discounts or reward vouchers by their id or code.


Library and Requirements

Available via the standard library only.

Does not require any database tables to be enabled.

Function Parameters
unset_discount(discount_data, recalculate_cart) Help
Name Data Type Required Default Description
discount_data string | int | array Yes FALSE Can be either a string, int, or an array of values, that the function will attempt to match against discount ids or codes within the cart data.
recalculate_cart bool No TRUE Define if all cart totals must be recalculated on success, regardless of whether the function has determined to do so or not.
The purpose of this is prevent multiple unnecessary recalculations of the cart if this function is used with other cart updating functions.
How it Works

The function loops through all the submitted 'discount_data' and attempts to match it against the id or discount code of discounts applied to the cart. If a discount matches the data, then it is removed from the cart session data.

If the discount that is being unset is a conditional discount that is auto applied by the cart when a defined quantity and value is reached, then the discount will be added to an excluded discount array. Discounts in this array are prevented from being automatically reapplied. See the 'excluded_discounts' and 'unset_excluded_discounts' functions for further information.

If no 'discount_data' is submitted, all manually set discounts and discount/voucher codes are removed.

Return Values

Failure:FALSE | An error message will be set.

Success:TRUE | A status message will be set.

Example
// Example #1 : Unset a discount code using a string or int.

$discount_data = 'EXAMPLE-CODE';

$this->flexi_cart->unset_discount($discount_data);
// Example #2 : Unset multiple discount codes using an array.

$discount_data = array(
'EXAMPLE-CODE-1',
'EXAMPLE-CODE-2',
'example_id'
);

$this->flexi_cart->unset_discount($discount_data);

unset_excluded_discounts()

Re-enables all discounts and reward vouchers that have be excluded from being applied to the cart.

Typically, these are discounts that are automatically applied by the cart when the discounts required quantity and value of items has been added to the cart.


Library and Requirements

Available via the standard library only.

Does not require any database tables to be enabled.

Function Parameters
unset_excluded_discounts(recalculate_cart) Help
Name Data Type Required Default Description
recalculate_cart bool No TRUE Define if all cart totals must be recalculated on success, regardless of whether the function has determined to do so or not.
The purpose of this is prevent multiple unnecessary recalculations of the cart if this function is used with other cart updating functions.
How it Works

The function unsets all excluded discount data from the carts session data.

Return Values

Failure:n/a

Success:TRUE | A status message will be set.

Example
$this->flexi_cart->unset_excluded_discounts();