Page tree
Skip to end of metadata
Go to start of metadata



Shipping options are provided by carriers and referred to as service layer agreement (SLA). Each SLA represents shipping method configuration that is setup for a specific shop for a set of fulfilment centres with a specific set of payment options available, besides various other configurations on date exclusions and lead times. Carriers can be assigned to one or more shops. Once the carrier is assigned to a shop all its SLA become available for selection subject to contents of the cart. 

Another crucial configuration is shipping and billing address location. Each location is represented by a "state", which may refer to district, state, region or province within a country. Countries and states are shared by all shops hosted on the platform as these are geographical locations and are unlikely to differ. Therefore the countries and statesdata are entered by platform administrator whereas applicable shipping and billing countries can be configured for individual shop by a shop manager.

Once the location data is entered and the shop is configured for carrier, shipping and billing locations, these options will become available to the customer on the website during checkout and address management.

Here is the overall depiction of the process:

Figure 1: Shipping methods and locations configuration data organisation



In terms of the platform carriers represent delivery companies that offer one or more shipping service referred to as service layer agreement (SLA). Each SLA is locked into use by specific set of fulfilment centres and payment methods.

The rationale for this configuration is that each fulfilment centre will have its own configuration of delivery methods and specific delivery methods in their own right will be applicable only to specific payment options.

Consider a fulfilment centre that allows only "Collect in store" options with a payment option to pay at collection versus another fulfilment centre that only "delivers to home" via courier and required full payment before shipment. Both of these fulfilment centres can be configured for a single shop. Checkout API will automatically split the order by fulfilment centre and present relevant shipping options to the customer. 

Further to the configuration of assignments of fulfilment centres and payment methods there is an option filter the availability of a shipping method by currency. Each SLA requires a valid price record to be available, which is similar concept to the products availability.

Managing carriers


Basic information

Basic information about carriers comprises of name and description and corresponding localisable fields.

In default theme localisable name of the SLA is displayed to the customer on the shipping method selection page. However checkout API provides information about both carrier and SLA giving the option for custom themes to perform a two step selection or grouping of the information on the UI. Decision on the representation of the shipping method option on the UI depends on many factors: 

  • do people trust one carrier over another in a certain country? if so it may be better strategy to display carriers.
  • does business offer same type of delivery option with different costs via multiple carriers? if so it may be better strategy to display carriers as well as SLA.
  • does business have very few clearly defined shipping options (e.g. standard, next day, weekends)? if so it may be better strategy to simply show list of SLA to customer.

Shop assignments

Carriers and their SLA can be shared by multiple shops since it is possible to assign carrier to multiple shops. This especially works well in multi shop and marketplace installations where clear options could be given to be shared by all shops/vendors. 

The platform does not restrict carrier by name and it is possible to define "same" carriers dedicated to different shops. Consider situation where "UPS" carrier is used by two shops "SHOP10" and "SHOP20" where each shop requires different SLA. It is possible to enter "UPS (SHOP10)" and "UPS (SHOP20)" carrier names and put same name into localisable name "UPS" that will be visible to customers thus making it look the same to the customer. Then separate SLA could be defined for each carrier and carriers "UPS (SHOP10)" and "UPS (SHOP20)" assigned to SHOP10 and SHOP20 respectively thus establishing a one to one link between carriers and shops.

To create and immediately assign carrier use the shop's "Carriers" tab

Carrier "shops" tab represents an inverse view of the shop instance "carriers" tab and allows to see all shops that have selected carrier assigned to them.

Managing carrier SLA


Basic information

Carrier SLA purpose is twofold: 

  • explains the customer how delivery is to be fulfilled
  • provides configuration to calculate shipping costs and delivery timelines

How the delivery is to be fulfilled is implied by name and description of the SLA, which should be descriptive enough for the customers to fully understand the delivery terms and conditions. The actual configuration is defines by an number of parameters:

Configuration Purpose
SLA typeMode of calculation for costs and delivery times
Named day

Flag to instruct the system that customer can choose a desired day for the delivery. The choice will be allowed between min and max days (see configurations below).

For example if Named day flag is set and today is 1st on November and min days is 10 and max days is 20 then the earliest delivery date the customer can choose is 10th of November and the latest is 30th of November, excluding any dates or weeks days which are set in exclusions

Guaranteed deliveryFlag to instruct the system that carrier guarantees to deliver the item in X days (subject to exclusions). X in this case in represented by min days. Max days in this setup will be equals to min days.
Min days

Minimal number of days required to deliver the items.
(warning)  Note this is carriers min days. If fulfilment centre has its own lead time set than this lead time is added to this min days value when calculating the earliest possible delivery date 

Max days

Maximum number of days required to deliver the items. If this is not a guaranteed or a named day delivery this parameter allows to determine estimated time frame for delivery. E.g. "You item will be delivered between 1st Nov and 10th Nov"
(warning)  Note this is carriers max days. If fulfilment centre has its own lead time set than this lead time is added to this max days value when calculating the latest possible delivery date 

Optional billingFlag that instructs the system that billing address is not needed to place an order
Optional deliveryFlag that instructs the system that delivery address is not needed to place an order (e.g. collect in store)
Payment methods selection

Exact list of payment methods that this delivery method supports. In case of multi delivery the final payment options list must satisfy all deliveries SLA configuration.
(warning)  If deliveries have SLA that contains mutually exclusive payment options the customer will not be able to place the order. So ensure that default payment option is available in all SLA.

Fulfilment centres selection

Exact list of fulfilment centres that this delivery method supports. Allows to customise specific delivery options per fulfilment centre.
(warning)  If deliveries have product SKU that is from fulfilment centre that has no shipping SLA associated with it the customer will not be able to complete checkout. Ensure that all fulfilment centres have as least one SLA available in the shop

Exclusions: Not available for customer types (CSV)Allows to specify customer types which should not be allowed to use given delivery option
Exclusions: No delivery XExclude deliveries by week day. Used when calculating estimated delivery and named delivery available dates
Exclusions: No delivery on specific datesExclude deliveries by specific date or date range. Used when calculating estimated delivery and named delivery available dates

Shipping costs depend on the pricing calculation configurations, which are specified by "SLA type". 

Note that shipping promotions are independent of this calculation and is applied after shipping costs calculation has been performed. 

"SLA type" describes predefined method of calculation of shipping costs. The following calculation methods are supported out of the box:

SLA type Calculation Method 

Allows to specify fixed price per delivery.
Overall cost calculation is: fixed price x number of deliveries in order

Free Tells the system that there are no cost associated with delivering this item. This could be used for digital deliveries or "collect from store". 
Weight & Volume

Determines appropriate delivery cost by calculating weight and/or volume of products in cart (using product's custom attributes PRODUCT_WEIGHT_KG and PRODUCT_VOLUME_M3 respectively).
Overall cost calculation is: price @ quantity tier where (tier is either total weight in KG or volume in M3) 

External Extension point, not used by core API  

Offline  3.7.0+ 

The cost is deemed as 0 for the purpose of basket calculation and shipping is annotated with "#OFFLINE#" promotion tag on shipping price. This tag is then used to hide elements from the checkout screens and email templates. In Admin the shipping cost are also hidden to denote that they are not parts of the order calculation.

This method should be used when calculation of the shipping cost has complex logistics e.g. base rate within city + additional price per km beyond the city borders and in addition to this weight and volume implications

For free shipping as promotion we recommend using "Fixed" SLA type and then specify 100% discount promotion for order value greater than zero. This will provide additional promotional messaging to encourage the customer.

Above types are common approaches to calculation provided out of the box. More complex implementations can be easily supported using custom delivery cost calculation strategy implementations.

Pricing and Tax

Tax for shipping is setup in the tax configuration by using carrier SLA SKU (first column in the SLA table) as SKU in the tax config entry. Because SLA SKU is treated as any other SKU all tax configurations that apply to regional taxes will apply to shipping methods as well. 

Prices for all SLA are specified in the price lists using carrier SLA SKU as if it was any other product SKU. Because SLA SKU is treated as any other SKU all price records will follow the same rules of best value calculation, with validity time frames and policies correctly applied. Table below shows which prices need to be setup for each type of SLA (for examples consider that SLA SKU is SHIP0001):

SLA TypePrice records requiredExampleNotes


[SKU]=[List price]


SHIP0001=4.99Fixed price requires a simple list price entry

[SKU]=[List price]
SHIP0001=0.00Free price requires a simple list price entry with 0.00 list price. This is a marker price to indicate that a price exists in the shop for this SLA and it is therefore available
[SKU]_KG=[List price for quantity in KG]
[SKU]_KGMAX=[List price for max KG allowed]


Weight based pricing where quantity tier is the weight in kilograms for all products in the delivery (counted by adding up values of PRODUCT_WEIGHT_KG attribute). In the example the price for parcels up to 5kg is 5.99, 5-15kg is 9.99, 15kg and more parcels are not allowed.


[SKU]_KG=[List price for quantity in KG]
[SKU]_KGMAX=[List price for max KG allowed]



Volume based pricing where quantity tier is the volume in cubic meters for all products in the delivery (counted by adding up values of PRODUCT_VOLUME_M3 attribute). In the example the price for parcels up to 5m3 is 5.99, 5-15m3 is 9.99, 15m3 and more parcels are not allowed.

Fulfilment centres 3.5.0+ 

Fulfilment centre that offers the product in a shop may have specific delivery requirements which may be:

  • Specific delivery options
  • Specific lead times for standard and/or backorder items
  • Specific exclusion dates and days of the week

Therefore each SLA specifies exactly which fulfilment centre is is applicable for. Once the order is split into deliveries each delivery will contain specific delivery options applicable to it.

Fulfilment centre lead times are taken into account when calculating estimated delivery time and earliest date available for delivery. 
If Partial deliveries available fulfilment centre option is switched off it will block multiple delivery option in checkout and force all items (standard + backorder) to be delivered as one delivery

Payment methods

In terms of business process shipping method directly influences the choice of available payment methods. For example it does not make sense to display "Payment to courier" option when the delivery method is "collect from store" or "post". 

The platform provides mechanism for establishing a relationship between carrier SLA and payment gateways that are applicable. Note that this relationship does not account for shop configurations. Thus when customer progresses through checkout in a specific shop they will be able to select only payment option available to the shop if it is applicable to the carrier SLA.

Here is the depiction of this process:

Once the payment gateways are specified the options will become available on the payment screen of the checkout.

  • No labels