Shipbeat Magento Module. Installation and user guide

(1)

Shipbeat Magento Module

Installation and user guide

(2)

1. Module installation

This guide explains how the Shipbeat Magento Module is installed, used and uninstalled from your Magento Community Store.

If you have questions or need support to get the extension to work as intended in your Magento shop, please don’t hesitate to contact us via email support@shipbeat.com or via phone +45 7060 5021.

This section will walk through the installation of the Shipbeat Magento Module (henceforth referred to as the module). The installation steps of the module take place in the

backend/admin panel of your Magento setup. By default, the backend/admin panel can be found under www.your-domain.com/admin.

1.1 Regular installation

1. Navigate to the following menu System > Magento Connect > Magento Connect Manager

2. Click the [Choose File] button and select the zip-file containing the module (see image 1)

3. Click the [Upload] button

4. Upon successful upload, navigate back to the frontpage of the backend/admin panel. 5. Navigate to the following menu System > Configuration > Shipping Methods >

Shipbeat

a. Enter your unique token (see box 1)

b. Make sure the “Mode” option is set to “Production” (alternatively “Test”

mode is available)

c. Enter a customer relevant title in the “Title” option (this title is displayed above the shipping options in the checkout)

d. Select whether you want to automatically send New Shipment emails to your customers once you print the label. We recommend you leave it at “Yes”

e. You can also choose for the invoice to be created at the same time you print labels. This feature is currently experimental and might not work as expected f. Disable other shipping methods (like FedEx or DHL) through the “Enabled”

menu option

6. For configuration of the shipping methods, navigate to System > Shipbeat > Shipment configuration

(4)

Image 1 - Upload of the module in the Magento Connect Manager

Where do I find my token?

The token required for the installation of the module can be obtained in multiple ways: ● _{From the confirmation page after signing up on}www.shipbeat.com/signup/ ● _{From the welcome email after signing up on}www.shipbeat.com/signup/

● _{Directly from a Shipbeat representative at}_{support@shipbeat.com} or call +45 7060 5021

Box 1 - The different ways to obtain a Shipbeat token

1.2 Multi-store installation

The module also supports multi-store Magento installations. The installation of the module in a multi-store setup is identical to the regular installation except for step 5.a and 5.b. Instead follow these instructions for the two steps:

● _5.a - Change configuration scope based on your preference (see image 2) ● 5.b - Enter the token you want to use for this configuration scope

(5)

This step completes the installation of the module. The next step is configuring the extension with the delivery methods you wish to offer your customers.

1.3 Installation for SUPEE-6788 and Magento CE 1.9.2.2 customers

“Magento's SUPEE-6788 patch is a mess for developers. There are a number of breaking changes, affecting 800+ of the most popular extensions and many customizations.”

- ParadoxLabs Luckily, it’s easy to get Shipbeat Module to work with this patch. All you have to do is:

1. Go to Admin > System > Permissions > Blocks 2. Click "Add New Block"

3. Add and allow the following blocks: ○ shipment/tracking

○ shipment/email_labels_return ○ shipment/email_tracking_url ○ shipment/email_shipping_address That’s all there is.

(6)

2. Configuring the module

Configuring Shipbeat Shipping Module is easy. If you signed up via our website, you will already have a Shipbeat Shop configured for you. If you want to make modifications to delivery methods and packaging options available to you, a Shipbeat Support employee will be happy to assist you.

In the following steps you will learn how to use Shipbeat within your Magento Store, and how to configure delivery methods.

2.1 Configuring delivery methods

Once you’ve completed the module installation, navigate to System > Shipbeat > Shipment configuration. You will be able to set up Delivery methods in this view.

(7)

The module downloads available delivery methods from Shipbeat and displays them here. You are able to edit the display name of a delivery method and the description. All changes are saved as you type.

Why can’t I customize return deliveries?

Return deliveries are only visible in the backend to the merchant, therefore they don’t have a description field.

Box 2 - Return deliveries do not appear in the checkout flow

Image 4 - Delivery methods displayed during checkout

2.1.1 Delivery method “Delivery point”

Delivery point delivery methods include special functionality in your frontend. Once your customer clicks on a delivery method for a delivery point, a map with available delivery point destinations will appear in an overlay (see image 5).

(8)

Image 5 - Overlay showing the delivery point destinations

This overlay is fully responsive and will adjust itself to your customer’s screen resolution. It works on all devices: PC, laptop, tablet and mobile.

Image 6 - The responsive overlay

2.1.2 Multi-store setup note

If you are running a multi-store Magento installation, be sure to enter a token for each configuration scope. After that, you can easily switch between stores using the “Jump to”

menu (see image 7).

(9)

Your shipping configurations will use your default currencies and measurement units you have defined for those stores in Magento settings.

Box 3 - The module adapts to your Magento settings

Image 7 - The jump to menu

2.1.3 ACL permissions

Make sure to give access to “Shipbeat” and “Shipment configuration” resources to appropriate roles. They can be found under “System” tree.

Image 8 - Shipbeat resources are enabled for this role

2.2 Configuring shipping rates

Shipping rates allow you to define rules for shipping fees in your checkout. They also define which delivery methods will be visible to your customers. If no rates match customer cart’s contents, no delivery methods will be displayed.

(10)

Image 9 - Shipping rates tab

If you click [+ Add rate] button, you will be able to fine-tune pricing on various input

parameters. Once you are satisfied with the pricing policies, click the [Save rates] button to save them.

Image 10 - Various rule definitions. See explanation in section 2.2.3

2.2.1 Input parameters

Delivery method Select which delivery method this rule will apply to.

Cart value The final shopping cart value including taxes but excluding shipping cost.

Cart weight Total shopping cart weight - the sum of all product weights in the cart. Countries Countries that this rule applies. Defaults to “All countries”. If “All

countries” and “Not Denmark” are selected, this rule will apply to all countries except Denmark.

Postal code A postal code of the destination. Only numeric postal codes are supported.

Pass through Shipbeat is able to return an estimated price for this delivery. You can pass through this price to your customers. If you check this box, then you are able to add additional cost to the passed through price using price column. E.g. pass through

(11)

Asterisk as a value - what does it mean?

Asterisk (*) means that any value will be accepted - it’s a wildcard. Values are inclusive [from, to].

Box 4 - It’s easy to define your custom policies

2.2.2 Actions

Dragging Conflicting rules are resolved from top to bottom. If a matching rule is found on the top, it will be used over the ones in the bottom.

You can rearrange rules by dragging them up and down. You can drag by clicking the “four horizontal lines icon” ( ) to the left of the rule. Deleting You can delete a rule by clicking the [Delete] link to the right. You will

be asked to confirm before the rule is deleted.

2.2.3 Examples

Example 1 - Delivery method “Delivery Point” is free when cart value is more than 499.99

Example 2 - Delivery method “Home Delivery” has a reduced price when cart value is above 499.99

Example 3 - Shipping to Greenland has a fixed price of 139.99 regardless of cart value or weight

(12)

Example 5 - Shipping to home is dependant on weight – the more it weighs, the more it costs

2.3 Configuring box sizes

Shipping rates are based on both dimensions and weights depending on the carrier. Shipbeat can allocate your shipments to the most affordable carrier. To help reduce your shipping cost you can specify which boxes you ship with and relate the boxes to a weight range for the shopping cart. As an example you would likely use a small box if you are shipping only a 1 kg and a larger box if you ship 4 kg.

The more accurate this is, the more we can reduce your shipping cost as well as improve the shipping rates you give your customers if you are using the “Pass through” pricing rules.

Image 11 - Default box is set to “M parcel, 55x37x10 2kg” for this store

If you click the [+ Add box] button, you will be able to specify which box you typically use for a certain range of cart weight. Once you are satisfied with your box rules, click the [Save boxes] button to save your changes.

(13)

Image 12 - Rules for choosing the right box

2.3.1 Input parameters

Box Select which box this rule will apply to.

Cart weight Total cart weight that’s a sum of all product weights in the shopping cart.

2.3.2 Actions

Dragging You can rearrange rules by dragging them up and down. You can drag by clicking the “four horizontal lines icon” ( ) to the left of the rule. Conflicting rules are resolved from top to bottom. If a matching rule is found on the top, it will be used over the ones in the bottom.

Deleting You can delete a rule by clicking the [Delete] link to the right. You will be asked to confirm before the rule is deleted.

2.4 Sort order in the checkout

By default, delivery methods are sorted by price, but you can also allow Shipbeat to decide the best option to be displayed on top. Usually, this option will be the cheapest for you, but not necessarily cheapest for your customers. You can also sort delivery methods manually based on Shipping rates priority.

(14)

(15)

3. Handling orders

Once your customers place orders, they are ready to be processed by Shipbeat. The module seamlessly integrates with the Order Information page, providing extra functionality to print various labels and tracking the order without downloading the label.

You can access these actions via the top button toolbar (see image 14) or the action bar in the “Shipping & Handling Information” window (see image 15).

Image 14 - [Print label] button is added by Shipbeat Magento Module to the “Order Information” page to help make shipping frictionless

Image 15 - More actions are available from the “Shipping & Handling Information” section in the “Order Information” page

Image 16 - Actions available after the label has been printed

The actions available are: [Print label] (and [Reprint original label]), [Create a new label], [Create a return label], and [Track order].

I can’t see [Track order]?

(16)

Box 5 - Tracking is only possible after you’ve printed a label.

3.1 Printing labels

The module makes it easy to print the labels for your orders. Simply click the [Print label]

button and your browser will begin downloading a PDF that you can later print. If you have enabled, New Shipment email will be sent, too. If you have “Silent Print” enabled for your Shipbeat account, a label will be sent to your printer instead.

3.2 Return deliveries

There are times, when your customers need to return a package back to you. In those cases, you can generate a return label, that you can e-mail (or print and send via post) to your customers.

3.3 Creating additional labels

Sometimes you will need to split your order into multiple packages. In those cases, you can use the [Print a new label] action. An extra label will be generated and downloaded by your web browser. It will also appear in an “Additional labels” section of the “Shipping & Handling information” window once you refresh the page.

Image 17 - One return and two extra outbound labels available for download

(17)

If the Track & Trace service is applicable to this order, the [Track order] action will allow you to see the tracking information for this order. If you click on it, a popup will appear displaying the tracking information provided by Shipbeat.

Image 18 - Track and Trace information for an order, that consists of two labels

3.6 Mass actions

Shipbeat Magento Module adds mass actions to All Orders grid page. Mass actions allow you to perform a certain task for multiple orders, like printing labels for orders that have been placed in the last 12 hours.

(18)

Image 19 - Shipbeat specific mass actions.

Please refer to section 3 in order to learn more about what each mass action does.

3.7 Changing shipping address & delivery method

If you or your customer made a mistake in the shipping address, you can fix it if you haven’t printed the label yet. To do so, click [Edit] link in the Shipping Address section and enter the new address.

Image 20 - Change shipping address by clicking “Edit” link in the top right corner

Once you’ve been redirected back to the order overview page, you will see that Shipping & Handling Section contains available shipping methods for this method. You need to choose one of the methods before you can print the label.

(19)

Image 21 - You can now select a new delivery method for this order

Once the delivery method is changed, you can print the label as usual.

When changing the delivery method, shipping price will not be modified as to not to invalidate the payment information.

3.7.1 Changing only delivery method

If you wish to only change the delivery method, click [Edit] link in the Shipping Address

section and then click [Save Order Address] button to keep the same address. The module will ask you to select a new delivery method.

(20)

4. Other features

4.1 Emails

4.1.1 Adding shipping address (for delivery points) to your emails

When your customers select a delivery point as their shipping destination, it’s address is not automatically printed in your emails. You need to replace default Magento shipping address block with Shipbeat’s one.

Replace this:

With this:

4.1.2 Adding carrier name

You can display the carrier name by inserting this block:

4.1.3 Adding tracking link

You can add tracking URL to your transactional emails using the following block:

4.1.4 Adding a “Download Return Label” link

You can add a “Download Return Label” to your emails by adding the following block:

(21)

When your customer clicks on this link, they will be able to download a label for shipping items back to your warehouse.

4.2. Track & Trace

Shipbeat Magento Module adds a Track & Trace page on your webshop. You and your customers may access it on www.myshop.com/shipment/tracking. Tracking information can be displayed by entering order number into the “Order number” field.

Tracking page is also available for you to use as a block. Put this code in any of your CMS pages where you want the tracking functionality to become available:

This is really useful if you want to do upsales or just show additional information next to tracking details.

If you want to insert a Track & Trace link for your customer’s purchases in the New Order or New Shipment email templates, follow the instructions in 4.1.2 Adding tracking link.

(22)

5. Supported checkout modules

Shipbeat Magento Module currently officially supports the following checkout methods: ● Magento’s Default Onepage Checkout

● _{OneStepCheckout (4.1.3) from}_{www.onestepcheckout.com}. ● Checkout from www.magentomoduler.dk

● Fire Checkout by TemplatesMaster ● IWD Checkout

If you have any further questions regarding support for checkout modules, don’t hesitate to contact us at support@shipbeat.com or call +45 7060 5021.

5.1 Recommended configuration for OneStepCheckout

Shipbeat Magento Module is fully compatible with OneStepCheckout, but there are certain configuration options that you need to set in OneStepCheckout settings. Navigate to System > Configuration > Sales > OneStepCheckout.

Under general settings

● Ensure that default country is set (e.g. Denmark) ● Select shipping method if only one available: Yes ● Hide shipping method: No

Under AJAX update shipping/payment methods ● Enable AJAX save billing: Yes

● AJAX save billing fields: Country, Postcode

This is all it takes to configure OneStepCheckout for Shipbeat Magento Module. The module supports OneStepCheckout 4.1.3. You can check which version of OneStepCheckout you are using in the following file:

(23)

6. Changelog

1.1.1 - Maintenance release - 2016-01-28

● Improved support for GoMage Light and Unicode Systems Express Checkout | One Step Checkout

● Fixed a bug with comments

1.1.0 - Changing address, excluding countries & bug fixes - 2016-01-20

● Fixed a bug in Safari where it was impossible to add a comment to a delivery point ● Sometimes delivery point popup was opened even though the delivery method did

not allow optional delivery point selection

● Original delivery method name is now displayed at all times in the configuration screen

● Ability to modify shipping address and delivery method

● Address block in the email will display correct address even if it isn’t Shipbeat order ● Comments are no longer missing when printing additional labels

● Lifted the limitation of being able to define only 17 countries in shipping rates ● Ability to exclude certain countries from shipping rates

● A version number is now added to JS

● An API call is no longer made if no suitable shipping rates are found

1.0.0 - We’re out of beta! - 2015-12-21

This release marks a milestone when we are finally out of beta and fully stable and feature rich. Thank you all for a wonderful year and being with us. Here’s to the years to come! This release includes the following updates:

● Delivery point search has been improved with free text search. You can enter address, city, country, etc.

● Added a new block that will allow you to display Carrier’s name in email templates ● The module now exports a list of shipping method for use in other modules or

promotion rules ● Improved test suite

(24)

● Added support for international delivery points

● Some modules caused shipping descriptions to be rendered twice ● We will fallback to country if area cannot be found by postal code ● Module actually respects permissions from ACL

● Better support for very heavy items ● Better support for multi-currency setup

● Shipment configuration only displays the stores that have valid tokens

● It is now more clear which store is being edited in the Shipment Configuration ● Tracking page will no longer freak out if the custom theme doesn’t comply with

Magento standards

● Improved Track & Trace page to display events even if main delivery has none

0.8.1 - Maintenance - 2015-11-25

● Added experimental feature that allows invoice to be created at the same time as the label is printed

● Disclosing module version when doing API requests ● Magento PHP Library update

0.8.0 - Shipment configuration & small improvements - 2015-11-16

This update contains some breaking changes to the delivery methods setup. Please be aware that when you install it, your shipping rates will be authoritative source for retrieving enabled delivery methods during customer’s checkout. If no matching shipping rate rules are found for a delivery method, it will not be shown during the checkout.

Shipment configuration updates:

● Removed checkbox to enable/disable a delivery method

● Available delivery methods are determined by matching shipping rate rules ● Removed fallback shipping price

● Initial rules are created during installation

● It is now possible to sort delivery methods in the checkout manually

● Fixed a bug where you had to manually update cache after saving sorting preference Other updates:

● Danish translations for the customer facing part of the module

● Additional labels and return labels now have an order reference assigned to them. This helps us identify the orders in the Shipbeat App

(25)

● Sometimes an email or a phone number would go missing from Magento’s Shipping address. The module is now able to fallback to billing address in those cases

● Added installation instructions for SUPEE-6788 to Readme

● Fixed a bug where quotes were not returned due to trailing spaces around a postal code

Various improvements - 0.7.5 - 2015-11-03

● You can no longer reprint original label from batch actions. Use “print additional labels” instead

● “Print label” button is now renamed to “Reprint original label” once you’ve printed the label for the first time

● It is now possible to let Shipbeat reorder your delivery methods in the checkout ● It is now possible to combine asset files (JavaScripts and Stylesheets)

● If there is an error when printing a label, it will be added to the order’s Comments History

● Track & Trace window has been expanded to display tracking information for deliveries related to the order

● Fixed a bug where secure URL was not used in the checkout when enabled ● Fixed a bug where delivery point address was displayed twice if two delivery point

delivery methods were available in the checkout

● Fixed a bug where delivery point map was not displayed in the backend

Compatibility with various checkouts - 0.7.4 - 2015-10-26

● Improved compatibility with IWD checkout

● Improved compatibility with checkout by Nybohansen ApS ● Improved compatibility with FireCheckout

Various improvements - 0.7.3 - 2015-10-19

● Track & Trace completely revamped. Carrier’s name, carrier’s T&T reference and direct link to them is now exposed. Carrier’s timestamp and event description is now exposed as well

● Fixed incompatibility with modules that expose their bundled jQuery in the global space

● Delivery points popup is more compatible with various themes ● In some rare cases the Quote ID was not available to the observer

● It was theoretically possible to complete checkout without selecting a delivery point ● When changing delivery point, you had to enter a comment from scratch. Not

(26)

● Creating deliveries with Shipbeat is now more stable and gives better error notifications

● Small refactorings, speed improvements, code cleanups

● Due to concurrency issue, it was possible that delivery points got switched up in the database

● Better error logging ● Test suite improvements

Maintenance and minor new features - 0.7.2 - 2015-09-23

● Shipping email is now sent when printing a label. To disable: System > Configuration > Shipping Methods > Shipbeat > Send "New Shipment" email when printing label > No

● Added caching to API calls, so that repetitive calls are not made on Checkout page ● Added new and improved test suite. All tests are green

● There were some small bugs in Firefox and IE on Shipment Configuration page. They're fixed now

● Silent printing is now supported. Get in touch with support to enable it for your account

● Deliveries with Shipbeat are now registered on checkout success to speed up silent label printing

● PHP Wrapper update ● Better API error logs ● ACL fix

● Email block for correct shipping address (including delivery point addresses) ● Email block for correct tracking URL

● Email block for allowing your customers to download a return label by following a link Upgrade notice. Your old email blocks will not work and will produce errors. Please setup email templates according to "4.1 Emails" section.

Shipping policies update - 0.7.1 - 2015 08 19

● Some Shipbeat API calls weren’t executed using a correct token in Magento Multistore setup

● Improved country field functionality so that merchants can enter multiple countries per rule. It also adds a nice GUI that converts country codes to country names ● Removed functionality to register deliveries

● Renamed “Pricing policies” to “Shipping rates” and “Packaging policies” to “Box sizes”

(27)

● When submitting empty fields for Shipping rates and Box sizes, they will be treated as wildcards

Shipping policies - 0.7.0 - 2015 08 14

● Completely revamped backend and introduced shipping policies ● Better feedback for API errors

● Updated Shipbeat PHP wrapper, which now includes better error descriptions ● Various performance optimizations under the hood

● Displays carrier and packaging information in order details view

● Fixed a bug where it was possible to create an order without saving Shipbeat quote ● OSC has now improved compatibility

● Lots of other small fixes and refactorings

Upgrade notice. After the upgrade is complete, manually flush the cache storage and visit Shipment Configuration page in order to migrate existing data.

Various fixes - 0.6.3 - 2015 07 15

● Magento quote no longer required to render delivery point address in transactional emails

● Correct carrier code is now set for tracking information (fixes a problem where it was impossible to print packing slips)

● Order increment ID is now set as tracking ID

● Fixed a bug where a customer was able to get through checkout without attaching Shipbeat quote to Magento quote

Various fixes - 0.6.2 - 2015 07 13

● Updated Shipbeat PHP wrapper

● No longer possible to use "test" or "demo" endpoints – only "production" endpoint is now available. "Test" and "Production" modes are still available and the module requires "Production API Key" from now on

● Fixed a small bug where it wasn't possible to determine "production" and "test" mode values for internal use

● Configuration page now forces delivery method response to be parsed as JSON ● If a quote cannot be retrieved during transactional email processing, delivery point

address will be returned as an empty string

● Google Maps external script is now loaded via JavaScript instead of Layout XML files ● Removed overrides of Magento's Page HTML blocks

(28)

Batch processing - 0.6.0 - 2015 05 28

Batch processing related improvements:

● Removed “Ship” button for Shipbeat orders (now it’s easier to print labels) ● Initial shipment order is now created at the same time the order is placed ● Order actions bar is now always displayed on the order information page ● “Track” link only visible when order tracking information exists

● Rearranged order actions buttons

● “Register delivery“ link visible if delivery has not been created

● “Register delivery” and “Print label” are added to the top actions bar

● Labels are now persisted in the database to eliminate latency between your Magento store and Shipbeat API

● Error labels are generated in case there are problems with real labels

● Cronjob has been added to persist missing labels for registered deliveries in the database

● Added mass actions

Other improvements and changes:

● Developers now have a “Demo” mode available for their stores that simulates Production environment’s speed with dummy database

● Username/Password authentication combination has been removed from settings ● Renamed some configuration options and values

● Fixed a bunch of exceptions in the Shipment Configuration page ● A bunch of refactorings to improve code quality

● Updated old and added new tests

Delivery points - 0.5.0 - 2015 05 11

Delivery point related improvements:

● It is now possible to retrieve delivery points for multiple carriers under the same delivery point shipping method

● Added a template directive for displaying delivery point address in the emails

● Delivery points can now be selected when making new orders or re-ordering from the backend

● Magento Onepage Checkout now displays selected delivery point address in the sidebar after shipping method has been saved

(29)

● A friendly button indicating the possibility to change delivery point after it has been selected is now displayed next to a delivery point shipping method

● Google map is reinitialized each time delivery point popup is shown. This helps prevent scaling issues in case the browser was resized in between popup display/hide events

● When encountering an error while saving delivery point, Save button no longer stays inactive

● Postal code is now cleared in between popup show/hide events

● Magento Onepage Checkout used to display delivery point address even though shipping method was not synced with Magento

● Optimization for API calls when looking up multiple delivery point quotes in the same session

Other improvements:

● Shipping method descriptions can now have line breaks in them

● Address is now created right before the delivery in the admin instead of during quote lookup

● Fallback to country area is now removed. This used to give incorrect quotes when customer enters incorrect postal code

Internal changes:

● Moved to Grunt build system away from Codekit ● New test cases for new features

● Fix an exception notification spam in logs ● Code refactoring in tests

● Code refactoring under the hood

● Better way to inject JavaScript into frontend ● PHP short open tags are no longer there

Return deliveries - 0.4.0 - 2015 04 23

● Return delivery is now a special kind of delivery method visible for the merchant ● Return delivery can be created from order overview

● Return label can be downloaded from order overview

OSC compatibility - 0.3.1 - 2015 04 21

(30)

● Ensures that delivery method is always synced with DB ● Update the backend when deselecting delivery point ● Address is now created right before creating a delivery

● User action is no longer available when only one shipping method is available ● User gets a visual clue to select a delivery point when only delivery point method is

available

● Delivery point address is displayed even at initial page launch

● Error message is displayed if initially no delivery points could be found Other changes:

● Descriptions can be added to shipping methods ● Delivery Point popup mobile view improvements And more small fixes under the hood...

Initial release - 0.3.0 - 2015 04 13

● Display Shipbeat shipping methods to your customers ● Custom price for shipping methods

● Price override over X basket value ● Track & Trace of shipped packages ● Print labels

Shipbeat Magento Module. Installation and user guide