nShift Checkout - Magento 2 - Manual

Latest version: 1.1.99 released on 2024-05-14

System requirements

Magento 2.3.6+, 2.4+

Functions

Shipping selector widget for ordering or shopping cart at checkout
Create reserved shipments
Create booked shipments
Create shipping labels
Create tracking links
Include tracking links in order emails
Change shipping option after incoming order
Print multiple shipping labels as one document
Process deliveries on several orders simultaneously

Before we start

Note: To be able to use this extension you will need a nShift Checkout account. You will also need the API Connect add-on. If you don’t have any nShift Account today, you can order it yourself using our module.

Questions and support regarding nShift
Questions or support regarding nShift services or settings at Unifaunonline.com, please contact nShift directly. Use e-post: [email protected] or phone: +46-31-725 35 50

Regarding this manual and instructions
This manual does not cover all possible angles of nShift Checkout, just the extension. All configurations regarding carriers, options and add-ons is made inside your nShift account. If you have any questions about the extensions, please feel free to contact us.

Notes about Magento 2.4.0
Magento introduced an issue that prevents any shipping labels to be created (un-related to this module), so you need to follow instructions here to patch away the issue.

Notes about Magento 2 default checkout
The default checkout destination country is set from the setting SALES > Tax > Default Tax Destination Calculation > Default Country

Notes about Klarna Checkout
The default checkout destination country is set from the setting GENERAL > General > Store Information > Country

Installation

Follow instructions below to properly install the extension according to your license.

In order to be able to install the module you first need to contact Oktagon to receive a username and password. We also need the name of the domain (incl. dev, test, staging etc) the module is going to be installed.

Add Composer repository (not need if you have bought the module at Magento 2 Marketplace)

composer config repos.oktagon composer https://username:[email protected]/

Note: Replace username and password above with your produce license credentials that you received earlier

Install module via Composer

composer require "mediastrategi/uodc":"^1.0"

Note: Enter your produce license credentials that you received earlier

Install & Setup

Run the following commands to install and setup the module. Test on a staging server first. Enter username and password when prompted. (Replace xx_YY or the other languages with the ones you use.)

bin/magento maintenance:enable
bin/magento cache:flush
bin/magento module:enable Mediastrategi_UODC
bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento cache:enable
bin/magento setup:static-content:deploy en_US sv_SE xx_YY
bin/magento maintenance:disable

Restart varnish (optional)

service varnish restart

We also have a tutorial "How to use nShift Checkout for Magento2" with english subtitle.

Setup

After you have installed this extension you need to follow these steps.

Login to the Magento 2 dashboard
Click in the menu SALES > nShift Checkout > Dashboard
Click "Get started", the screen will guide you through the setup process and the configuration

Configuration

Most configuration-settings have descriptions in Magento 2 but for more information read on in this section.

Options > Sender reference prefix

The Shipping label will show order number as standard but with the prefix “msudco_”. You can change the prefix if needed. If you leave it blank it will show the standard prefix Edit the Sender reference prefix here.

Options > Parcel Contents

You can choose between Product names, Product categories or Empty to show up as Contents on the shipping label. Make your choice under Parcel contents.

Product names shows name of content, ex Blue Cotton Shirt XL
Product categories show category of the product, ex Shirts
Empty leaves Contents field blank on shipping label

Everything OK?

Look at the “Options” tab in the middle and see if the Status shows “Site configuration OK” or not. If not, look at the error message and fix the problem.

Setup product dimension attributes

By default the module sends height, length and width arguments to nShift API in checkout but these attributes do not exist in Magento 2 from scratch, if you want to use them first create your product attributes and then select them under the tab “Product Dimension Attributes”. Remember to always use meters as your dimension unit.

Setup customs declaration attributes

Create a product attribute for HS-Code and Country of Origin and select them under the tab “Product Customs Declarations Attributes”. You will also need to use the Configurator to set up when customs declaration should be used.

Enable widget

nShift provides a JavaScript-widget that can be enabled, this will change the behavior of the module in several ways, only one shipping method will be in the system for nShift Checkout but interacting with the widget will alter the details of the method (price, title, pick-up point, etc). For details of the different settings see the nShift Documentation.

If you select 'No' on Install CSS our module will provide a base CSS that is easily customized.

Turn on Automation

In the dashboard click Sales / nShift Checkout / Dashboard and then Configuration

Click the “Automation” tab at the top.

Then choose:

Status = Enable
Order Status = Processing (is standard)
Package Type = Unspecified Package (is standard)

Click the button called “Finish” to Save.

Now your incoming orders will be packed by auto.

PDF settings

In the dashboard click SALES / nShift Checkout / Dashboard, then click Configuration

Click the “PDF” tab and fill out your PDF-settings. The click Save up in the right corner.

Transsmart Customers

If you are a Transsmart customer select Yes in the option "I am a Transsmart customer", you will not be able to book shipments, print shipping-labels or use return shipments in Magento 2.

Dynamic Shipping Configurator

When to use the Dynamic Shipping Configurator

If you want to use separate return-shipments or customs declaration you need to use the configurator to setup when and how these should be used, click SALES > nShift Checkout > Dashboard, then Dynamic Shipping Configurator to start.

Enter a name for your new configuration and then click the Add button to add it.
Click the name of your new configuration to open it
Optionally select a service id to limit usage of this configuration to orders that uses the selected service
Optionally select destination countries to limit the usage of this configuration to orders that ship to specified countries
Optionally select customs declaration documents to use for shipments matching the selected criterias
Optionally select what return-shipment service to use for shipments matching the selected criterias
Optionally select if return-shipments should be created automatically when turn-shipments are being made

Return-shipments

How to use

If you have enabled return-shipments using the Dynamic Shipping Configurator or previous page you should see a return button on shipments that has return shipments enabled, but only if no return shipment exists for shipment already.

If you use automatic return shipments they should be created automatically when manually creating shipments, or creating shipments via the automation.

Orders and printing

When using Automation

If you turned on Automation you can see all orders in the Magento dashboard by click Sales > Orders in the main menu. The Automation has already created the package, tracking number and booking of carrier by auto. All you need to do is mark all orders and choose “Print Shipping Labels” from the Actions dropdown above the list of orders. This will create a pdf with all shipping labels for the chosen orders.



Note: Because you use Automation the orders may take some minutes to be seen in the order list, due to CRON.

When using regular Magento 2 order processing

You can see all orders in the Magento dashboard by click Sales > Orders in the main menu.
Click on the order you want to edit.
Click “Ship”-button in the top menu.



Scroll down to “Shipping Options” at the bottom and click on the “checkbox” called “Create Shipping Label”, then click on the “Submit Shipment…”-button.



Click “Add products to package”-button



Mark the products that you want to add to the package, then click “Add selected products to package”-button.



If you want to split an order into several packages, you can click “Add package”.
Fill out type, weight, length, width, height if you want to (only weight field is really needed). If you already added weight on the product page, it should be filled by auto.
Click “Save”-button up in the right corner.

Note: You now have two choices to print the shipping label.

Click “Shipments”-button in the left menu

Click on the order and scroll down to section called “Shipping and Tracking Information” and click the “Print shipping label”-button.





Or..

Go to Sales > Orders in the main dashboard menu. Mark the order and choose “Print Shipping Labels” from the Actions dropdown above the list of orders to print the shipping label for this order.

Tracking

How to track a shipment

To track a shipment, just click Sales > Shipments in the main dashboard menu.
Click on the order you want to track
Scroll down to the section called “Shipping and Tracking Information” and click on the link called “Track this shipment”.
Minor fixes with order references

Sandbox mode

nShift has no Sandbox mode yet, please ask nShift for a test account.

Ignore automation

On the order you can now find an "Ignore/Unignore Automation"-button. This can be used to ignore orders which should not be automated. Orders which fails being sent to nShift will also be marked as ignored instead of flooding nShift with invalid data rows.

On the order list view there is a new column which shows the number 1 if an order is ignored, otherwise it is empty.

Changelog

[1.1.99] Fix for Porterbuddy integration and more for Svea nShift
[1.1.98] Handle case were Svea nShift fails to register prebooking, added automation settings for Klarna nShift and Svea nShift integrations, using destination address only when fetching shipping options
[1.1.97] Fixed minor issues
[1.1.96] Added support for Svea Nshift
[1.1.95] [2023-12-14] Added setting for shipment notification during automation, added print rotation setting, fix for shipment data generation when missing categories
[1.1.94] [2023-11-10] Using hash in shipment reference to make it harder to guess tracking links
[1.1.93] [2023-11-01] Bug-fix for order mass action corrupting data
[1.1.92] [2023-10-03] Support for PHP 7.4 again that was lost in 1.1.91
[1.1.91] [2023-09-04] Support for running automation via REST API at /rest/V1/msuodc/runAutomation/:orderId/:totalWeight
[1.1.90] [2023-03-27] Improved type annotations in carrier model for third-party integrations
[1.1.89] [2023-03-21] Support for virtual quotes in widget mode and support for orders lacking shipping method
[1.1.88] [2023-02-23] Work on preventing the possibility of duplicate prebookings on a order shipment in some scenarios
[1.1.87] [2023-01-09] Storing API transactions only in debug mode
[1.1.86] [2022-11-04] Fix for checkout with widget and invalid shipping address, shipping methods are now visible in cart when widget mode is disabled
[1.1.85] [2022-10-27] Minor fixes with order references
[1.1.84] [2022-08-18] Various PHP 8.1 fixes, fixed persistence of selected add-ons in checkout in widget-mode
[1.1.83] [2022-08-17] Bug fix in automation when module order-data storage is empty
[1.1.82] [2022-07-26] Various bug fixes
[1.1.81] [2022-07-25] Fix for Klarna_Checkout in checkout
[1.1.80] [2022-07-25] Improved error-handling when connecting to nShift Delivery and nShift Checkout APIs
[1.1.79] [2022-07-14] Major refactor for Magento 2.4.4 support
[1.1.78] [2022-03-17] Removed nShift onboarding from module
[1.1.77] Improved resolving of license hostname in some environments
[1.1.76] Improvements in automation, general improvements
[1.1.75] When creating a new order with a shipping option from nShift Checkout and Transsmart account is enabled, the orders shipping address will be updated to the agent address
[1.1.74] Added support for converting Klarna KSS/KSA nShift shipping information on orders to be able to use our module for communicating with nShift, frontend CSS for Klarna Checkout from our module now only affects site if module is enabled in checkout
[1.1.73] Changed name of vendor and module to Oktagon nShift Checkout, improvement in agent support for Transsmart customers
[1.1.72] In automation if product is not found use order-item instead.
[1.1.71] Fixed encoding of agent data for Transsmart customers when using widget-mode.
[1.1.70] Added setting for multi-inventory source deduction algorithm when using automation. Added support for multi-inventory automated shipments. Improved error-recovery when creating automated shipments
[1.1.69] Improved with Widget + KCO iframe sync, added interface preference if installation is missing dotmailer-module
[1.1.68] Improved support for Transsmart customers
[1.1.67] Added "Ignore nShift Automation" so orders that fails when sent to nShift doesn't repeatedly create invalid shipments in nShift forever
[1.1.66] Fixed rare bug with multiple custom region selectors in widget mode, fixed bug with duplicate shipments when doing manual shipments with multiple packages
[1.1.65] Improvements in widget-mode surrounding session agent refreshing
[1.1.64] Added installation-wizard, improved comments around configuration-settings, moved all UDC-related screens to a common Dashboard.
[1.1.63] Added fix for when changing zip-code and an unavailable agent is left in session in widget-mode
[1.1.62] Added agents address1, zip-code and city to agent selector in legacy-mode
[1.1.61] Fixed potential JavaScript bug in cart and checkout (without widget) were there are no shipping alternatives
[1.1.60] Added support for Transsmart customers with a new module setting
[1.1.59] Fixed bug in REST PHP-DOC, admin UI and specific issue when using region-selector and KCO without widget-mode
[1.1.58] Fixed some rare errors in checkout, made it possible to use different designs for map, improved widget+Klarna KCO support for older Magento 2 versions
[1.1.57] Added support for map feature in widget
[1.1.56] Compatibility fix in checkout template for older Magento 2 versions
[1.1.55] Fixed rare bug with checkAvailableShipCountries()
[1.1.54] Fixed bug with wrong initial total price in Klarna Checkout when using widget
[1.1.53] Added CSP policy, added BASE_URL parameter to checkout, fixed bug with unavailable shipping method in default checkout
[1.1.52] Added option to custom region selector to update quote address
[1.1.51] Fixed bug with logged in customers with predefined zip codes
[1.1.50] Fixed bug with calling getAllItems() when data is not available in checkout
[1.1.49] Fixed bug with customs declaration printSet not being included. Fixed bug with widget method title i regular checkout summary
[1.1.48] Fixed bug with loading options.id, fixed bug with setting tocountry argument in checkout where destination country is missing, added settings for product dimension attributes, added support for customs declarations, added support for separate return shipments, fixed rare bug with missing agent id from checkout
[1.1.47] Added legacy support for changing shipping method and agent on order in admin, various stability improvements
[1.1.46] Added widget support for Magento 2.4, made it possible to set select agent on order in admin
[1.1.45] Support for Norwegian tracking links, added feature to change orders shipping method
[1.1.44] Now sends argument keepPreparedShipment to allow multiple shipments on same order
[1.1.43] Uses contact person name for contact field even if a company contact name is available
[1.1.42] Fixed wrong argument notice
[1.1.41] Added option for disabling suffix in generated prepare ids
[1.1.40] Fixed web-api warning and selected option when no selection is made
[1.1.39] Major refactor, added a ping-back request after order has been saved
[1.1.38] Fixed issue were Boolean URL parameters were encoded as integers. Improved 3rd party capability of altering shipping parameters. Improved identification of selected option carrier and service ids.
[1.1.37] Fixed bug in JSON extra options merging
[1.1.36] Added sensitive and environment configurations
[1.1.35] Work with multi-store configuration loading
[1.1.34] Added support for hierarchical shipping methods in widget, optimized ajax calls
[1.1.33] Added widget order fields to REST API
[1.1.32] Added support for pickup booking setting
[1.1.31] Added support for Official Javascript Widget and extra options
[1.1.30] Fixed bug with pre-selected add-ons not being saved on order
[1.1.29] Added support for sending state to API
[1.1.28] Improved support for Google Chrome carrier logos in checkout
[1.1.27] Improved error-handling when tracking without valid credentials
[1.1.26] Fixed bug on cart template were all options except selected disappeared when user selected one
[1.1.25] Package height, width and length are now calculated as the maximum value of all products instead of as a sum
[1.1.24] Improved support for attributes height, width and length via product model
[1.1.23] Improved width, height, length logic, made it easier to plugin argument generation
[1.1.22] Library added support for flattening hierarchical shipping options from API
[1.1.21] Agents are only displayed when customer has entered country and zip
[1.1.20] Agents are now only sent with quickId parameter for PLAB services
[1.1.19] General clean-up
[1.1.18] Magento Marketplace fixes and supports agent.id conversion to agent.quickId
[1.1.17] Added more information to PostNord agents to avoid fee
[1.1.16] Improve checkout templates in regular checkout
[1.1.15] Added automation admin user option
[1.1.14] Magento 2.2.6 compatibility
[1.1.13] A default pick-up agent is now selected
[1.1.12] Added support for custom package-types and receiver contact
[1.1.11] Optimizations to Klarna Checkout ajax requests
[1.1.10] Added support for forced API language
[1.1.9] Improved order data presentation if lacking add-ons, agent and carrier
[1.1.8] Fixed Klarna Checkout issue were price was not updated until selecting agent
[1.1.7] Renamed module and added support for external address change in checkout
[1.1.6] Fixed bug with valuePerParcel not working
[1.1.5] Changed column type of order meta data to avoid corruption in preparation for Magento 2 REST API support, improved error messages
[1.1.4] Added settings for order reference, value per parcel, removed receiver reference
[1.1.3] Added support for stored shipments
[1.1.2] Added language as argument for available shipping methods in checkout
[1.1.1] Fixed various javascript checkout issues and added support for Svea Checkout
[1.1.0] Fixed issue where cache was invalid
[1.0.9] Added better support for checkouts were zip is not sent via Ajax
[1.0.8] Fixed bug where pick up location and add-ons were not saved in original checkout
[1.0.7] Added support for new Klarna Checkout
[1.0.6] Made optional Zip Code and Country Selector for Klarna Checkout
[1.0.5] Better support for Bootstrap framework and Magento Marketplace
[1.0.4] Bug fix for add-ons with extra pricing and PLAB agent
[1.0.3] Supports Klarna Checkout with price add-ons
[1.0.2] Shipping rates are refreshed in checkout when changing country
[1.0.1] Added support for pick-up location and add-ons

Updated on: 14/05/2024