Summary
|
|
Introduction: JSON syntax, items and properties
If you have a question, use the following topic: http://www.magentocommerce.com/boards/viewthread/38223/
Since version 2.5, the syntax of configuration is full JSON JSON.
Example:
"ex0": {
"about": "National",
"label": "National",
"shipto": "AD,FR,MC",
"conditions": "{cart.price-tax+discount}<1000.00",
"fees": "1.30 + {table {cart.weight} in 0.5:5.30, 1.0:6.50, 2.0:7.40, 3.0:8.30, 5.0:10.10}"
}
}
The configuration is a JSON object containing properties.
Each property has a unique name, wich will serve as unique identifier.
Each property will consiste on a configuration item (also a JSON object).
Items have always a type property. This sets the type of the item:
The unique identifier
Each configuration item has a unique identifier. This unique identifier is then used to reference the item.
Example:
"europe": {
"label": "Europa",
"fees": 10
},
"us": {
"label": "US",
"fees": "{europe.fees}+20"
}
}
Warning: to avoid conflicts, use only the following characters a-z, A-Z, 0-9, - and _ to make the unique identifier.
You have also to avoid identifiers that match to any variable name (cart, product, item...).
method item
A method item allow to specify a shipping method.
Example with only required properties:
"ex0": {
"label": "Free shipping",
"fees": 0
}
}
Full example:
"ex0": {
"about": "Colissimo National",
"type": "method",
"label": "Colissimo",
"description": "Delivery within 24/48h",
"enabled": true,
"conditions": "range({cart.weight},0.2,1.0)",
"shipto": "FR(01,02,39600,/^25[0-9]{3}$/),CH,DE",
"billto": "FR",
"origin": "DE",
"customer_groups": "NOT LOGGED IN,Retailer",
"fees": "{table {cart.weight} in 0.5:5.30, 1.0:6.50}"
}
}
data item
A data item allow to specify data that can be used in shipping methods.
Example of data item:
"mydata": {
"type": "data",
"reference": "100"
}
}
Example of data usage:
"ex0": {
"type": "method",
"label": "Colissimo",
"fees": "{mydata.reference}*1.5"
}
}
type: the type of the item
This sets the type of the item:
- method: shipping method (default if not specified)
- data: data that can be used in shipping methods
- meta: informative data
"about": ,
"mydata": {
"type": "data",
"reference": "100"
},
"ex0": {
"type": "method",
"label": "Colissimo",
"fees": "{mydata.reference}*1.5"
}
}
about: comment on the item
You can add a comment to a configuration item.
"ex0": {
"about": "My comment",
"label": "Example with a comment",
"fees": 10
}
}
The label
The name given to the shipping method.
We can insert some data like the package weight in the label.
To do that, use the following variables:
- The shipping address:
{destination.country.name}{shipto.country_name}{destination.country.code}{shipto.country_id}{destination.region.code}{shipto.region_code}{destination.postcode}{shipto.postcode}
- {cart.weight}: the package weight
{cart.weight.unit}{cart.weight_unit}: the weight unit- See the full list of variables
"ex0": {
"label": "Colissimo ({cart.weight} / {shipto.country_name})",
"fees": 10
}
}
The above line will display for example "Colissimo (3.0kg / France)".
conditions
conditions property is specified as a formula (see introduction to formulas) that must return a boolean value (true or false).
"ex0": {
"label": "Price from 0 to 70 incl. tax",
"conditions": "{cart.price+tax+discount}<=70",
"fees": 10
},
"ex1": {
"label": "Price from 0 to 70 excl. tax",
"conditions": "{cart.price-tax+discount}<=70",
"fees": 10
},
"ex2": {
"label": "Price from 20 excluded to 70 included",
"conditions": "range({cart.price-tax+discount},20,70,false,true)",
"fees": 10
},
"ex3": {
"label": "Price from 10 included to 50 excluded",
"conditions": "range({cart.price-tax+discount},10,50,true,false)",
"fees": 10
},
"ex4": {
"label": "Weight from 0.5 excluded to 3 included",
"conditions": "range({cart.weight},0.5,3.0,false,true)",
"fees": 10
},
"ex5": {
"label": "Weight from 1 included to 5 excluded",
"conditions": "range({cart.weight},1.0,5.0,true,false)",
"fees": 10
},
"ex6": {
"label": "Only if free shipping",
"conditions": "{cart.free_shipping}",
"fees": 10
},
"ex7": {
"label": "Only if not free shipping",
"conditions": "!{cart.free_shipping}",
"fees": 10
},
"ex8": {
"label": "If any product has a 'color' attribute equal to 'Blue'",
"conditions": "{count items where product.attribute.color=='Blue'}>1",
"fees": 10
},
"ex9": {
"label": "If all products have 'size' option greater or equal to '1'",
"conditions": "{count items where product.option.size>='1'}=={cart.qty}",
"fees": 10
}
}
Addresses: shipto, billto and origin
The extension allow to filter addresses:
- The shipping address
destinationshipto. - The billing address billto
- The origin address origin
Country codes used are those used by Magento.
It's possible to specify region codes (only with shipto) or postcodes.
You can use the wildcard character * or regular expressions to filter postcodes.
A regular expression must start and end width the character /. If you want to use characters (, ) or ,, you have to escape them with character \ (ex: "FR(/^25\([0-9]{3}\)$/)").
You can use the case insensitive modifier (ex: "GB(/^PO.*$/i)").
"ex0": {
"label": "France, Germany, Switzerland, Spain, Italy",
"shipto": "FR,DE,CH,ES,IT",
"fees": 10
},
"ex1": {
"label": "France except Corsica",
"shipto": "FR-(2A,2B)",
"fees": 10
},
"ex2": {
"label": "Corsica",
"shipto": "FR(2A,2B)",
"fees": 10
},
"ex3": {
"label": "World except Germany and Corsica",
"shipto": "* - ( DE, FR(2A,2B) )",
"fees": 10
},
"ex4": {
"label": "Postal codes beginning with 25 using the wildcard character",
"shipto": "FR(25*)",
"fees": 10
},
"ex5": {
"label": "Postal codes beginning with 25 using a regular expression",
"shipto": "FR(/^25[0-9]{3}$/)",
"fees": 10
}
}
Tip
To shorten the seizure of countries, you can use the following variables:
- {address_filter.AF}: countries of Africa
- {address_filter.AS}: countries of Asia
- {address_filter.EU}: countries of Europa
- {address_filter.NA}: countries of North America
- {address_filter.SA}: countries of South America
- {address_filter.OC}: countries of Oceania
- {address_filter.AN}: countries of Antartica
- {address_filter.EU-27}: countries of the European Union
- {address_filter.DOM}: country codes of overseas french department
- {address_filter.COM}: country codes of overseas french communities
"ex0": {
"label": "Europa except France",
"shipto": "({address_filter.EU-27}) - (FR)",
"fees": 10
}
}
customer_groups
We can use the name or the ID of customer groups.
"ex0": {
"label": "NOT LOGGED IN and General groups",
"customer_groups": "NOT LOGGED IN,General",
"fees": 10
},
"ex1": {
"label": "NOT LOGGED IN and General groups by their ID",
"customer_groups": "0,1",
"fees": 10
},
"ex2": {
"label": "Retailer group",
"customer_groups": "Retailer",
"fees": 10
}
}
fees: the shipping fees
fees property is specified as a formula (see introduction to formulas).
"ex0": {
"label": "Fixed fees",
"fees": 10
},
"ex1": {
"label": "Fees table",
"fees": "{table {cart.weight} in 0.5:5.30, 1.0:6.50}"
},
"ex2": {
"label": "Formula",
"fees": "0.1 * {cart.price-tax+discount} + 10.00"
},
"ex3": {
"label": "Combination",
"fees": "0.1 * {cart.price-tax+discount} + {table {cart.weight} in 0.5:5.30, 1.0:6.50} + 10.00"
}
}
tracking_url
The use of tracking_url property is reserved for experienced users. If you don't understand the instructions below, it is recommended that you avoid using this feature.
The tracking_url property overrides the field "Tracking URL" of an Owebia Shipping shipping mode. So you can specify a tracking URL foreach shipping method rather than one for all shipping mode.
To automatically insert the tracking number in the tracking URL, you must use {tracking_number}.
"ex0": {
"label": "Example of tracking URL for the carrier Colissimo",
"fees": 10,
"tracking_url": "http://www.coliposte.net/particulier/suivi_particulier.jsp?colispart={tracking_number}"
}
}
Magento does not support tracking links but tracking statuses. The extension Owebia Shipping 2 provides an HTML link instead of the status, link allowing you to go on the carrier's website and follow the progress of the parcel.
When the tracking URL is built by the extension, the only information available is the tracking number and there was nowhere an access to the shipping method selected. In order to find the tracking URL in the configuration, you must specify the shipping method inside the tracking number, for example: colissimo:8Lxxxxxxxxxxx where colissimo is the code of the shipping method selected.
If no code is specified (if you enter only the tracking number), the URL used will be the one of the shipping mode.
To answer a recurrent question, Magento displays the tracking status from the back office or front office. If you want to insert the tracking URL in shipping mails, you need to develop yourself the retrieval of tracking URL and its incorporation in the mail, in fact, the Owebia Shipping extension simply provides customizable shipping methods without making big changes to Magento core to reduce incompatibility and update problems.
If you get a blank popup when you click on the tracking link, your problem is most likely related to the fact that you did not specify the code of the shipping method in the tracking number (see instructions above) and your global field "Tracking URL" is empty.
There are currently no plans to change this feature.
enabled
Allow to activate or desactivate the shipping method.
The value must be boolean.
"ex0": {
"enabled": true,
"label": "Example with activation",
"fees": 10
}
}
Introduction to formulas
Properties fees and conditions are specified as formulas.
Mathematical signs available:
- operators: *, /, + and -
- modulo: %
- brackets: ( et )
- boolean operators &&, and, ||, or, ==, <, >, <=, >=
- binary operators & and |
- operators group C ? X : Y (ex: "{cart.price_exluding_tax}>100 ? 15*{cart.weight} : 20*{cart.weight}")
Variables available:
- {cart.weight}: full package weight
- {cart.qty}: items count in cart
- {cart.price-tax+discount}: price excluding tax after discount
- {cart.price+tax+discount}: price including tax after discount
- {cart.price-tax-discount}: price excluding tax before discount
- {cart.price+tax-discount}: price including tax before discount
- See full list of variables
You can put spaces and line returns in formulas (to air).
Functions available:
- rounds: round(x), floor(x), ceil(x)
- absolute value: abs(x)
- maximum: max(x,y)
- minimum: min(x,y)
- random integer: rand(min,max)
- power: pow(x,puissance)
- PI number: pi()
- square root: sqrt(x)
- logarithm: log(x) for the natural logarithm or log(x,base)
- exponential: exp(x)
Ability to use advanced features like: casting to integer (int) casting to floating number (float), comparison with null or boolean values true and false.
You can also use advanced features such as rates tables, copy of a property of another method, special functions, usage of product's attributes and options or usage of custom variables.
When you use alphanumeric variables, you can escape them with quotes or you can use the autoescape syntax {{ }}.
"ex0": {
"label": "Escaping with quotes",
"conditions": "'{cart.coupon_code}'=='test'",
"fees": 10
},
"ex1": {
"about": "Since version 2.4.5, {{cart.coupon_code}} will be replaced by 'moncoupon' or by null depending on its value",
"label": "Auto-escaping",
"conditions": "{{cart.coupon_code}}!='test'",
"fees": 10
}
}
Variables available
The following variables can be used in different properties of shipping methods (in particular in properties conditions and fees).
- The cart:
- {cart.weight}: package weight
{cart.quantity}{cart.qty}: items quantity{cart.price_excluding_tax}{cart.price-tax+discount}: price excl. tax after discount{cart.price_including_tax}{cart.price+tax+discount}: price incl. tax after discount- {cart.price-tax-discount}: price excl. tax before discount
- {cart.price+tax-discount}: price incl. tax before discount
{cart.coupon}{cart.coupon_code}{free_shipping}{cart.free_shipping}: shipping offered (by a rule in Magento) [true/false]{cart.weight.unit}{cart.weight_unit}{cart.weight.for-charge}{cart.weight_for_charge}: weight of goods whose delivery is not offered (by a cart price rule in Magento)
- The customer group:
{customer.group.id}{customer_group.id}{customer.group.code}{customer_group.code}: name of customer group- {customer_group.*}: property of customer group (ex: {customer_group.tax_class_id})
- The customer:
- {customer.id}
- {customer.attribute.*}: attribute of the customer (ex: lastname, firstname, group_id...)
- {customer.attribute.*.value}: in case of attributes of type dropdown, {customer.attribute.*} returns the id, to get the value you must use {customer.attribute.*.value}
- {customer.*}: same as {customer.attribute.*} if the variable isn't defined (ex: {customer.id} is already defined)
- Custom Variables (since version 1.4.0.1 of Magento):
- {customvar.*}: Magento custom variable (ex: {customvar.my_var})
{{customVar code=*}}: use the syntax above
- The shipping address:
{destination.country.name}{shipto.country_name}{destination.country.code}{shipto.country_id}: the country code- {shipto.region_id}
{destination.region.code}{shipto.region_code}- {shipto.street}
- {shipto.city}
{destination.postcode}{shipto.postcode}
- The billing address:
- {billto.country_name}
- {billto.country_id}: the country code
- {billto.postcode}
- {billto.*}: property of the billing address (ex: {billto.city})
- The origin address:
{origin.country.name}{origin.country_name}{origin.country.code}{origin.country_id}: the country code{origin.region.code}{origin.region_id}- {origin.city}
- {origin.postcode}
- The store:
- {store.id} {store.code} {store.name} {store.address} {store.phone}: id, code, name, address and phone number of the store
- The current date:
- {date.timestamp}: UNIX timestamp of current date
- {date.year} {date.month} {date.day} {date.hour} {date.minute}
- {date.weekday}: weekday for current date from 0 (Sunday) to 6 (Saturday)
- The request object:
- {request.*}: property of the request object (Mage_Shipping_Model_Rate_Request) parameter given by Magento (ex: {request.package_qty}). Use the "Debug" option to have more details on available properties.
Special functions in formulas
You can use special functions in formulas.
List of special functions:
- min(x, y, ...) : calculate the minimum of several values (possibly more than two values). If one value is null, it is ignored.
- max(x, y, ...) : calculate the maximum of several values (possibly more than two values). If one value is null, it is ignored.
- range(value, min, max, include_min, include_max) : returns true if value is between min and max. By default, include_min and include_max are set to true.
- substr(string, start, length) : returns a segment of a string.
- in_array(value, array(value1, value2, ...)) : returns true if the value is in the array.
- array_match_any(array(value1, value2, ...), array(value1, value2, ...)) : returns true if any value is in both arrays.
- array_match_all(array(value1, value2, ...), array(value1, value2, ...)) : returns true if both arrays have the same values.
"ex0": {
"label": "Example with min function",
"fees": "min({cart.weight},{cart.price+tax+discount},{cart.qty})"
},
"ex1": {
"label": "Example with range function",
"conditions": "range({cart.weight},1.0,3.0)",
"fees": 10
},
"ex2": {
"label": "Example with substr function *",
"conditions": "substr('{cart.coupon_code}', 0, 5)=='free_'",
"fees": 10
},
"ex3": {
"label": "Example with in_array and strings *",
"conditions": "in_array({{cart.coupon_code}}, array('free1', 'free2'))",
"fees": 10
},
"ex4": {
"label": "Example with in_array and numbers",
"conditions": "in_array({cart.qty}, array(10,20,30))",
"fees": 10
},
"ex5": {
"label": "Example with array_match_any",
"about": "5 x weight of products contained in categories 2 or 3",
"fees": "{sum product.weight where array_match_any(product.categories.id, array(2, 3))}*5.0"
},
"ex6": {
"label": "Example with array_match_all",
"about": "5 x weight of products contained in category 2 and in category 3",
"fees": "{sum product.weight where array_match_all(product.categories.id, array(2, 3))}*5.0"
}
}
* About strings escaping, refer to the introduction to formulas.
Make a copy of a property of another method
It is possible to make a copy of a property in another using the syntax below.
You can use this technique in all properties (conditions, fees, ...).
"colissimo": {
"label": "Colissimo",
"shipto": "AD,FR,MC",
"conditions": "{cart.price-tax+discount}<1000.00",
"fees": "1.30 + {table {cart.weight} in 0.5:5.30, 1.0:6.50, 2.0:7.40, 3.0:8.30, 5.0:10.10}"
},
"ex1": {
"label": "Copy of conditions from another method",
"conditions": "({colissimo.conditions}) and ({cart.weight}>=0)",
"fees": 10
},
"ex2": {
"label": "Copy of fees from another method",
"fees": "({colissimo.fees}) + 15.00"
}
}
Using table
In a table, you can include or exclude a limit value with characters [ et ]:
"f0": {
"label": "Upper limit included",
"fees": "{table {cart.weight} in 1.0]:5.00}"
},
"f1": {
"label": "Upper limit excluded",
"fees": "{table {cart.weight} in 1.0[:5.00}"
}
}
In a table, you must specify the reference value. For this, we can use one of the available variables.
You can also use a formula to define another reference variable.
"ex0": {
"label": "Table with cart weight",
"fees": "{table {cart.weight} in 0.5:5.30, 1.0:6.50}"
},
"ex1": {
"label": "Table with cart quantity",
"fees": "{table {cart.qty} in 10:5.30, 20:6.50}"
},
"ex2": {
"label": "Table with price incl. tax",
"fees": "{table {cart.price+tax+discount} in 15.00:5.30, 30.00:6.50, *:10.00}"
},
"ex3": {
"label": "Table with price excl. tax",
"fees": "{table {cart.price-tax+discount} in 15.00:5.30, 30.00:6.50, *:10.00}"
},
"ex4": {
"label": "Table with user defined value",
"fees": "{table ceil({cart.weight}/10) in 1:5.30, 2:6.50}"
}
}
Using switch
In a switch, you must specify the reference value. For this, we can use one of the available variables.
You can also use a formula to define another reference variable.
"ex0": {
"label": "Switch with coupon code",
"fees": "{switch {{cart.coupon_code}} in 'coupon1':5.30, 'coupon2':6.50, null:10.00, *:7.50}"
},
"ex1": {
"label": "Switch with shipping country",
"fees": "{switch {{shipto.country_id}} in 'FR':5.30, 'BE':6.50, 'DE':10.00, *:7.50}"
}
}
Using product properties
In order to match to Magento Models, the version 2.4.8 of the extension adds a separation between item and product. An item is a product variation with some options. Each item has a quantity.
List of available properties:
- The item:
- item.qty: the quantity in cart
- item.price-tax+discount: the price excl. tax after discount
- item.price-tax-discount: the price excl. tax before discount
- item.price+tax+discount: the price incl. tax after discount
- item.price+tax-discount: the price incl. tax before discount
- item.option.*: option (depends on product)
- The product:
product.quantity: use item.qty- product.attribute.*: attribute
List of interesting attributes:- sku
- name
- weight
- price (as defined in product)
- special_price (as defined in product)
price-tax+discount: use item.price-tax+discountprice-tax-discount: use item.price-tax-discountprice+tax+discount: use item.price+tax+discountprice+tax-discount: use item.price+tax-discount
- product.attribute.*.value: value of the attribute
In case of attributes of type dropdown, product.attribute.* returns the id. To get the value, you must use product.attribute.*.value - product.*: same as product.attribute.* if variable is not defined (ex: product.category is defined)
product.option.*: use item.option.*- First category of the product:
- product.category: name of the category
- product.category.id
- product.category.*: attribute of the category (ex: product.category.is_active)
List of interesting attributes:- is_active
- name
- ...
- All categories of the product (returns an array, explanation section) :
- product.categories: array of categories names
- product.categories.id: array of categories ids
- Attribute set of the product:
- product.attribute_set: name of attribute set
- product.attribute_set.id
- product.attribute_set.*: attribute of attribute set (ex: product.attribute_set.attribute_set_name)
- product.stock.*: attribute of product stock
List of interesting attributes:- is_in_stock
- qty: product stock
- ...
"ex0": {
"label": "If at least one product has an attribute 'color' equals to 'Blue'",
"conditions": "{count items where product.color=='Blue'}>0",
"fees": 10
},
"ex1": {
"label": "If all products have the option 'size' greater or equal to '1'",
"conditions": "{count items where item.option.size>='1'}=={cart.qty}",
"fees": 10
},
"ex2": {
"label": "Different SKU count",
"conditions": "{count distinct product.sku}",
"fees": 10
},
"ex3": {
"label": "Sum of all options 'size' is greater than 30",
"conditions": "{sum item.option.size}>30",
"fees": 10
},
"ex4": {
"label": "Minimum price excl. tax without discount of products in cart is greater than 10",
"conditions": "{min item.price-tax-discount}>10",
"fees": 10
},
"ex5": {
"label": "Maximum value of option 'size' is lower than 50",
"conditions": "{max item.option.size}<50",
"fees": 10
},
"ex6": {
"label": "Count products in stock",
"conditions": "{count items where product.stock.is_in_stock==true}",
"fees": 10
}
}
Available prefixes list:
- count: count (always followed by items)
- count distinct : distinct count (always followed by a property)
- sum : sum (always followed by a property)
- min : minimum (always followed by a property)
- max : maximum (always followed by a property)
It's possible to specify conditions that must be met by products to be taken into account. To do this, simply add where followed by a formula.
If the property type is Yes/No, you should use true/false or 1/0 without quotes.
"ex0": {
"label": "Example property of type Yes/No: 0",
"conditions": "{count items where product.attribute.colissimo_allowed==0}",
"fees": 10
},
"ex1": {
"label": "Example property of type Yes/No: false",
"conditions": "{count items where product.attribute.colissimo_allowed==false}",
"fees": 10
}
}
If the property type is Drop-down and you want to make a comparison with the value rather than with the id, you must use the following syntax:
"ex0": {
"label": "If the color attribute's id is different to 1",
"conditions": "{count items where product.color.id!=1}",
"fees": 10
}
}
"ex0": {
"label": "If the value of color attribute is different to 'Bleu'",
"conditions": "{count items where product.color.value!='Bleu'}",
"fees": 10
}
}