v2.1.x AddCharge Manager (MndAddChargeManager) -EN

DateChange
20.05.2016
First public version of the documentation for version 1.0.0
27.06.2016
Updated documentation for version 1.1.0
  • Supplier country restriction for deposit
  • Plugin configuration for the announcement of the deposit specific for supplier country for not announced users
25.08.2016
Updated documentation for version 1.2.0
  • New Feature: Deposit information now in product exports available.
  • Discontinuation configuration option for "unknown delivery country"
01.09.2016
Updated documentation for version 1.2.1 and following
  • Configuration option for "mode" was removed
16.02.2017

Updated documentation for version 2.0

  • First version in english Shpware store released
  • New feature: set custom price of surcharge for customer groups


For template customization, in the past you could use article-mode (modus==500) to detect a surcharge article.

This does no longer work from version 2.0. The modus value is that of a shopware discount article in the basket. (== 4)

You can use the new field "mnd_addcharge_modus" which is available in the basket details and order details. The value is "500". (new surcharge types might come in the future)

28.04.2017

Updated documentation for version 2.1

  • New feature: surcharge calculation can be disabled for selected customer groups.




Introduction

With the plugin MND Add Charge Manager you can define surcharges and link them to articles. Surcharges become distinct articles with ordernumbers in the Shopware basket and order which will be calculated accordingly.

Typical applications could be:

  • Bottle deposit
  • Bulky goods surcharge
  • Handling fees

Special features of the plugins

  • ERP compatibly: Surcharges are distinct articles in the shopware basket and order! Ordernumbers can be custom values.
  • Surcharges are calculated per article amount. I.e. with order amount 10 = 10x surcharge is being factored.
  • You can define VAT setting per surcharge article
  • Name and description can be custom defined.
  • You can define multiple surcharge articles and link them to as many articles as you like
  • Multiple surcharges can be linked to one article
  • Deposits can be limited to one or several shipping-countries
  • You can use surcharge information in the Shopware product feed
  • You can set custom prices for customer groups
  • Surcharge calculation can be disabled for selected customer groups
Surcharges are placed in the basket as shopware discount articles and factored with default shopware process.

Screenshots

Display on the article detail page:

Display in Article Listing:

Display in the basket of goods:

The surcharge is displayed as basket article (like a discount article). Additionally an info is being displayed in the article for which the surcharge is being added. This is to show which articles have surcharges.

Of course, you can customize your template as you like.

Installation

The installation is being done as usual about the Shopware Plugin Manager.
Further information about the installation process in Shopware:

Plugin-Installation: http://community.shopware.com/Lizenzierung-und-Installation-von-lizenzpflichtigen-Plugins_detail_1340.html
Plugin-Manager: http://community.shopware.com/Plugin-Manager-ab-Shopware-5_detail_1856.html)

Plugin-Configuration (Experts Settings)


Usage

Configuration in the backend

Select the submenu item "Additional Charges Manager" in the main menu:


Create/Edit Surcharges

Click "Add" to create a new surcharge or click on the pen icon in the grid to edit an existing one.
A deposit can be assigned to several articles and be limited to certain shipping countries.


  • Customers that are not logged in: Surcharges are displayed according to the default customer group of the Shopware sub-shop. In checkout surcharges are calculated based on the selected shipping country
  • Customers that are logged in or newly registered: Surcharges are displayed according to the shipping country of the customer.


Creating a Deposit


The following fields are relevant for the configuration of a deposit:

Feld

Beschreibung
Internal NameName of the surcharge, which is used in the backend.
Name

Name of the surcharge, which is visible in the shop.

order number of

Order number of surcharge, how it should be saved in the order (is for example then also passed to ERP / inventory management system).

an ordernumber must be unique
Although technically possible, you should use for ordernumbers only sign A-Z, a-z, 0-9 and "-". 
I.e. no umlauts, special characters or blanks.
Description
Short description of the surcharge. It is shown by the article in the shop below the surcharge price info.
Price Type
Here you can set the input type for the price (incl. VAT.) / (excl. VAT.)
Price
Price of surcharge (decimal separator is a dot)
VAT
Set which VAT configuration should be used

Add different prices for Customer Groups

In the configuration tab of the surcharge you can also set exceptions for different selected groups.

All Customer Groups are listed. You can edit a row via double clicking.

To activate a special configuration for a customer group you have to activate the field "Exception". If "Exception" is inactive, the default handling will be used.

Now you can set a different price or deactivate the surcharge calculation completely. When "disable surcharge" is active, no surcharge will be added for this customer group.

Example for a customer group exception

The Customer Group "Shopkunden" no surcharge will be calculated.

For "Händler" a surcharge of 0.2 incl. VAT will be used.

Assign from Articles

You can add a surcharge for an article via the name of the article or the ordernumber.
It is only possible to link the surcharges to articles in this windows. A feature to link surcharges in the article details window might come in the future.


The surcharge was successfully linked to the article


Limit surcharges to shipping countries

A surcharge can be limited to (shipping) countries. The surcharge will then only be calculated when the country in the shipping address of the user corresponds to the selected countries.

You can change in the plugin configuration if a user that is not logged in to the storefront is able to see surcharges.

For surcharges limited to countries we recommend using an according name or description for the surcharge. E.g. "handling fee for delivery to france".


The surcharge was limited for the supplier country, in this case "Switzerland".


You should clear the Shopware cache (frontend and http-proxy) after changing surcharge configurations


Assigning two or more surcharges to an article

You can assign more than one surcharge to an article.

Together with limiting a surcharge to a shipping country, you can have special surcharges for different countries

If you use more than one surcharge you might need to customize your shopware template to make room for all surcharte information.


Template customization

For template customization, in the past you could use article-mode (modus==500) to detect a surcharge article.

This does no longer work from version 2.0. The modus value is that of a shopware discount article in the basket. (== 4)

You can use the new field "mnd_addcharge_modus" which is available in the basket details and order details. The value is "500". (new surcharge types might come in the future)


Use in the shopware productfeeds

In the templates of the productfeeds, a new field is added to the variable $sArticle

$sArticle.mnd_addcharge
This variable contains a JSON object with surcharge information:
VariableBeschreibungBeispielType
nameThe "Internal Name" of the surcharge.cansdeposit_1string
display_name
name of the surcharge for the customer
Reusable cans deposit
string
description

The description of the surcharge.

The description may contain newline characters. You should convert the value according to your target format. (e.g. CSV does not like line wraps)
reusable cans deposit is mandatory in Germany.
string
price
The gross price of the deposit in the currency opposed for the export
0.25float
tax
The tax rate of the deposit
19.00float


Examples of integration in productfeed template 

Spend deposit information as text

First we add a column to the header template of the productfeed

header
[...]
Deposit{#S#}
[...]
template
[...]
{assign var=addChargeData value=$sArticle.mnd_addcharge|unescape:'html'|json_decode:1}
{assign var="output" value=null}
{foreach $addChargeData AS $data}{append 'output' "plus {$data.price|format:"number"} {$sCurrency.currency} {$data.display_name}"}{/foreach}
{", "|implode:$output}{#S#}
[...]

Result:

Ergebnis
plus 0,25 EUR Test surcharge, plus 3,21 EUR Second Test Surcharge

Explanation:

the first three lines only prepare the output (they are not visible in the feed):
{assign var=addChargeData value=$sArticle.mnd_addcharge|unescape:'html'|json_decode:1}
Then we convert the JSON-String to an array. We use the array so we can use the values in a more civilized manner.
{assign var="output" value=null}
Then we create a variable which we assign values to. (still no output in the feed)
{foreach $addChargeData AS $data}{append 'output' "zzgl. {$data.price|format:"number"} {$sCurrency.currency} {$data.display_name}"}{/foreach}
Then we loop through all available surcharges and save the info to the "output" array.
{$data.price|format:"number"} 
this makes sure the prices are correctly formatted
{", "|implode:$output}
Finally, we output the surcharges separated by comma.


Add price of surcharge to article price

header
[...]
Price incl Surcharge{#S#}
{/strip}{#L#}
template
[...]
{assign var=addChargeData value=$sArticle.mnd_addcharge|unescape:'html'|json_decode:1}
{assign var="priceIncl" value=$sArticle.price}
{foreach $addChargeData AS $data}{assign var="priceIncl" value=$priceIncl+$data.price}{/foreach}
{$priceIncl}


Result:

Ergebnis
123.41
Then we convert the JSON-String to an array. We use the array so we can use the values in a more civilized manner.
{assign var="priceIncl" value=$sArticle.price}
We create a smarty variable and assign the price of the article to it
{foreach $addChargeData AS $data}{assign var="priceIncl" value=$priceIncl+$data.price}{/foreach}
Now we loop through every available surcharge and add the price to our variable
{$priceIncl}
Finally, we output the price as float value (without any formatting in this case).
 

Uninstall

The plugin is also uninstalled about the Plugin Manager.


When you uninstall the plugin, the surcharge configuration will not be removed. The configuration is saved in the following db tables:
  • mnd_add_charge
  • mnd_add_charge_articles
  • mnd_add_charge_customer_group_exception
  • mnd_add_charge_country