Shipbeat Magento Module. Installation and user guide

Transcription

1 Shipbeat Magento Module Installation and user guide

2 Table of contents 1. Module installation 1.1 Regular installation 1.2 Multi-store installation 1.3 Installation for SUPEE-6788 and Magento CE customers 2. Configuring the module 2.1 Configuring delivery methods 2.2 Configuring shipping rates 2.3 Configuring box sizes 2.4 Sort order in the checkout 3. Handling orders 3.1 Printing labels 3.2 Return deliveries 3.3 Creating additional labels 3.5 Tracking orders 3.6 Mass actions 3.7 Changing shipping address & delivery method 4. Other features 4.1 s 4.2. Track & Trace 5. Supported checkout modules 6. Changelog

3 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 support@shipbeat.com or via phone 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 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 s 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 From the welcome after signing up on Directly from a Shipbeat representative at support@shipbeat.com or call 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 Image 2 - Configuration Scope menu

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 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/ _labels_return shipment/ _tracking_url shipment/ _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. Image 3 - Configuring delivery methods

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 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 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). Which metrics and currencies are used?

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 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 Input parameters Delivery method Cart value Cart weight Countries Postal code Pass through Price Select which delivery method this rule will apply to. The final shopping cart value including taxes but excluding shipping cost. Total shopping cart weight - the sum of all product weights in the cart. 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. A postal code of the destination. Only numeric postal codes are supported. 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 The final price that will be visible to your customers.

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] Actions Box 4 - It s easy to define your custom policies Dragging Deleting 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. You can delete a rule by clicking the [Delete] link to the right. You will be asked to confirm before the rule is deleted Examples Example 1 - Delivery method Delivery Point is free when cart value is more than Example 2 - Delivery method Home Delivery has a reduced price when cart value is above Example 3 - Shipping to Greenland has a fixed price of regardless of cart value or weight Example 4 - Shipping price to the rest of the World is based on Shipbeat s estimated price

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 Input parameters Box Cart weight Select which box this rule will apply to. Total cart weight that s a sum of all product weights in the shopping cart Actions Dragging Deleting 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. 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 Image 13 - Changing sort order of delivery methods

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]? [Track order] is only visible after you ve printed a label for that 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 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 (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 3.5 Tracking orders

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 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 s Adding shipping address (for delivery points) to your s When your customers select a delivery point as their shipping destination, it s address is not automatically printed in your s. You need to replace default Magento shipping address block with Shipbeat s one. Replace this: {{var order.getshippingaddress().format('html')}} With this: {{block type="shipment/ _shipping_address" order=$order}} Adding carrier name You can display the carrier name by inserting this block: {{block type="shipment/ _shipping_carrier order=$order}} Adding tracking link You can add tracking URL to your transactional s using the following block: {{block type="shipment/ _tracking_url" order=$order}} Adding a Download Return Label link You can add a Download Return Label to your s by adding the following block: {{block type="shipment/ _labels_return" order=$order}}

21 When your customer clicks on this link, they will be able to download a label for shipping items back to your warehouse Track & Trace Shipbeat Magento Module adds a Track & Trace page on your webshop. You and your customers may access it on 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: {{block type="shipment/tracking"}} 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 templates, follow the instructions in 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 Checkout from 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 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 You can check which version of OneStepCheckout you are using in the following file: app/code/local/idev/onestepcheckout/etc/config.xml

23 6. Changelog Maintenance release Improved support for GoMage Light and Unicode Systems Express Checkout One Step Checkout Fixed a bug with comments Changing address, excluding countries & bug fixes 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 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 We re out of beta! 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 templates The module now exports a list of shipping method for use in other modules or promotion rules Improved test suite Various improvements

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 Maintenance 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 Shipment configuration & small improvements 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 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 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 Improved compatibility with IWD checkout Improved compatibility with checkout by Nybohansen ApS Improved compatibility with FireCheckout Various improvements 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 anymore

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 Shipping is now sent when printing a label. To disable: System > Configuration > Shipping Methods > Shipbeat > Send "New Shipment" 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 block for correct shipping address (including delivery point addresses) block for correct tracking URL block for allowing your customers to download a return label by following a link Upgrade notice. Your old blocks will not work and will produce errors. Please setup templates according to "4.1 s" section. Shipping policies update 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 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 Magento quote no longer required to render delivery point address in transactional s 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 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 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 Fixed an OSC test, which failed due to AJAX loader still being present on the page

28 Batch processing 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 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 s 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 Delivery point address is now displayed in order overview in the backend

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 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 OSC ( onestepcheckout.com ) related changes:

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 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 Create additional labels