Introduction

Introduction

Krokedil Shipping Connector is a plugin which makes it possible for you as a merchant to create or store shipments in nShift Delivery (previously Unifaun Online) directly from WooCommerce.

You can use Krokedil Shipping Connector (KSC) together with nShift Checkout, or you can use KSC with Klarna Shipping Assistant (KSA) which is a part of Klarna Checkout.


Requirements


  • Requires a nShift Delivery (previously Unifaun Online) account with nShift Checkout (previously Unifaun DeliveryCheckout) activated.

Installation


You install this plugin just like any other WordPress plugin:

  1. Download and unzip the latest release zip file.
  2. If you use the WordPress plugin uploader to install this plugin skip to step 4.
  3. Upload the entire plugin directory to your /wp-content/plugins/ directory.
  4. Activate the plugin through the ‘Plugins’ menu in WordPress Administration.

Configuration – plugin


  1. Navigate to WooCommerce -> Settings -> Shipping.
  2. Now Krokedil Shipping Connector is displayed as an available option in the horizontal menu at the top. Click on this link to access the Krokedil Shipping Connector settings.
  3. Debug log – Log events in the module. You can find the log by navigating to → WooCommerce → Status → Logs.
  4. nShift id – Your nShift API ID . Available from your nShift Delivery account. 
    In your nShift Delivery account, navigate to → Maintenance → API keys, and click on the search button. Now you will see a list of the API Keys in your account. Click on the “Pen” next to API Id. Now you will find the ID.
  5. nShift secret id – Your nShift Secret API ID. Available from your nShift Delivery account. 
    In your nShift Delivery account, navigate to → Maintenance → API keys, and click on the search button. Now you will see a list of the API Keys in your account. Click on the “Pen” next to API Id. Now you will find the Secret ID.
  6. nShift quick id – Your nShift Quick ID. Available from your nShift Delivery account.
    In your nShift Delivery account, navigate to  → maintenance → senders → and click on the search button. Now you will see a list of the API Keys in your account. Now you will see a list of the companies you have added and there you will see the Quick ID for each individual company.
  7. nShift printing favorite mapper – Map Delivery Option Title with Printing favorite Name.
    – The Delivery Option Title is the name of the shipping method displayed for the customer (and what is stored as shipping method in the order in WooCommerce).
    – The Printing favorite Name is available from your nShift Delivery account. In your nShift Delivery account, navigate to → Maintenance → Printing favorites → and click on the search button. Now you will see a list of your printing setups. You should add the Name on the one you want to use as a favorite in the plugin settings.

    The data saved in this setting must be saved as valid JSON for the mapper to work. You can check if your text is valid JSON at jsonlint.com. Here is an example how to enter the text:
{
	"Delivery Option Title": "Printing favorite Name",
        "DHL Home delivery": "DHL Home",
	"Postnord Service point": "Servicepoint"
}
  1. Fallback printing favorite – Enter your default nShift Printing favorite Name. Will be used if no match is found in the “nShift printing favorite mapper”. 

Order & shipment management

  1. Create Shipment or Store Shipment – Select where you want to handle the shipments and printing of the pdf shipment labels. Detailed explanation here.
  2. Create shipment action – Select when the shipment for an order should be created. Manually by the merchant or automatically when order status changes to Processing or Completed.
  3. Stored shipment status interval – Enter the interval in minutes, how often the plugin should check for stored shipment status changes in nShift. Leave blank to disable this feature.
  4. Multiple parcel booking – Enable the possibility to book multiple parcels in one shipment. Note: Not all shipping services support multiple parcels.
  5. Choose status on orders with Krokedil Shipping Connector – Enable if you want the order status in WooCommerce to change on orders edited with Krokedil Shipping Connector plugin.
  6. Label size – Select shipment and return shipment label size.
  7. Label X offset – Enter label X offset in mm. Use 0 for no offset.
  8. Label Y offset – Enter label Y offset in mm. Use 0 for no offset.
  9. nShift Track & Trace – Tracking link of the shipment will be available for customer and merchant. (Requires you to have the additional “Track & Trace” service active on your nShift-plus account).
  10. Send customer note – Send customer note email to customer when shipment is created.
  11. Customer note text – The text you want to send with the customer note email. Use {customer_name} where you want the customer name to be, and {tracking_link}, {tracking_id}, {pickup_point} for the link, ID and pickup location respectively.
  12. nShift parcel content text – General description of the content. Used when creating the shipment.
  13. Enable customs product fields – Tick the checkbox to add customs specific settings fields in product pages. Fields for Tariff code, Tariff description, Y code and Manufacturing country will be added if enabling this setting.
  14. Manufacturing country – Default country code, used for customs declaration document. Will be used if no Manufacturing country is entered on product level.

Configuration – Automatic label printing via PrintNode


  1. Enable automatic label printing via PrintNode – Tick this checkbox to enable automatic label printing via PrintNode.
  2. API key – The PrintNode API key.
  3. Print shipping label – Tick this checkbox to enable printing of shipping label via PrintNode when shipment is created in nShift.
  4. Printer ID – shipment label – Enter the Printer ID used for printing shipment labels.
  5. Print return label – Tick this checkbox to enable printing of return label via PrintNode when return shipment is created in nShift.
  6. Printer ID – return label – Enter the Printer ID used for printing return labels.
  7. Print customs document – Tick this checkbox to enable printing of customs document via PrintNode when shipment is created in nShift.
  8. Printer ID – customs document – Enter the Printer ID used for printing customs document.

Configuration – nShift Checkout


Displaying nShift Checkout directly in your WooCommerce checkout page is a new feature in the plugin that is still in beta.

This is how you configure nShift Checkout for WooCommerce:

  1. In the nShift Checkout section of the plugin settings you tick the checkbox Enable nShift Checkout.
  2. nShift Checkout placement – Select the hook used where nShift Checkout should be placed in the checkout page.
  3. Custom placement hook – Enter a custom hook where you want the nShift Checkout widget to be placed. Useful for embedded checkouts (like Klarna Checkout) with custom page templates.
  4. The shortcode [nshift_checkout] can also be used to place the nShift Checkout widget, but we recommend you to use one of the hook settings above.
  5. nShift Checkout ID – Enter the ID for the delivery checkout that you have prepared in your nShift account settings.
  6. From name – Used when booking a prepared shipment from Woo to nShift.
  7. From phone – Used when booking a prepared shipment from Woo to nShift.
  8. From email – Used when booking a prepared shipment from Woo to nShift.
  9. For every shipping zone you have created you need to add nShift Checkout as a new shipping method. Read more about Shipping method settings here.

Make sure that the nShift Checkout shipping method is the first shipping method in the list of available shipping methods for the zone that you are configuring.

If everything is working fine you should be able to see the shipping methods provided by nShift in a widget in the WooCommerce checkout page now:


Configuration – KSA / nShift


  • Configuration of Klarna Shipping Assistant together with nShift Checkout is something that you need to do in your Klarna and nShift backend accounts. 
  • It’s recommended that you start the configuration in a staging/test environment so you don’t break your production web store.

For the Shipping methods you need to set up in WooCommerce, you can read more about Shipping method settings here.

Read more about how to get started with KSA & nShift in this nShift documentation.


Conditional shipping methods


In some cases you might want to enable or disable specific shipping methods if a certain condition is met. For instance if an order contains bulky goods then delivery by bicycle might not be an option. To be able to handle these conditions the Klarna Shipping Assistant plugin sends WooCommerce Product Shipping Classes to Klarna/nShift. I you would like to disable a specific shipping method if a certain product shipping class exist in an order you can do the following:

  1. Add a shipping class to a product. In this case we call it Bulky.
  2. Navigate to nShift Delivery and edit the delivery checkout you are using for the KSA integration.
  3. Add a new Parameter. Give it the same name as the WooCommerce Shipping Class slug (in our case bulky). Set the Type to Boolean and specify the default value (in our case false).
  4. Now you need to configure each delivery option and specify the Condition.

    The shipping options that should be available only when an order doesn’t contain Bulky goods you enter bulky = false in the Condition box. 

    The shipping options that should be available only when an order does contain Bulky goods you enter bulky = true in the Condition box. 
  5. After saving the changes you can first test the Delivery checkout directly in nShift online test tool. When you see that it is working you can test it in Klarna Checkout.

Free shipping coupons 


In the same way as product shipping classes is passed to Klarna (and then forwarded to nShift), a tag named ksa_free_shipping is sent to Klarna if a coupon code is used that enables the customer free shipping. In the same way as the bulky example in the Conditional shipping methods section above, you can enable free shipping in the nShift Checkout configuration if ksa_free_shipping = true.


Create Shipment or Store Shipment


“Create Shipment” and “Store Shipment” is two different flows of the Krokedil Shipping Connector plugin and will make it possible for you to choose where you want to handle your shipments and pdf shipment labels. 

Create Shipment

If choosing “Create Shipment” the creation of the shipment will be done directly from WooCommerce. The pdf shipment label will be generated as soon as the “Create Shipment” button has been clicked. The pdf shipment label can be accessible through navigating to the specific order or through action buttons on the order overview page in WooCommerce backend.

Store Shipment

If choosing “Store Shipment” the creation of the shipment will be done from your nShift account. The shipment will be sent to a printing queue called “Stored Printings” in nShift. In order to create the shipment you will have to login to your nShift account and once the pdf shipment label is printed the shipment will be created.


Order management


Only orders made through Klarna Shipping Service will have the ability to have the shipment be created or stored.

Create Shipment

  1. Navigate to → WooCommerce → Orders.
  2. You can Create a shipment in multiple ways.
    1. Clicking the truck icon located to the right when viewing all orders.
    2. Selecting the Create Shipment option in the WordPress Bulk Action drop down menu.
    3. Navigating to the specific order and clicking the Create Shipment button located inside the metabox to the right.
  3. If a shipment was successfully created, the order note will display Shipment successfully created.

Store Shipment

  1. Navigate to → WooCommerce → Orders.
  2. You can Store a shipment in multiple ways.
    1. Clicking the arrow icon located to the right when viewing all orders.
    2. Selecting the Create Stored Shipment option in the WordPress Bulk Action drop down menu.
    3. Navigating to the specific order and clicking the Create Stored Shipment button located inside the metabox to the right.
  3. If a shipment was successfully stored, the order note will display Shipment successfully stored.

Cancel Shipment

  1. Navigate to → WooCommerce → Orders.
  2. Navigating to the specific order and clicking the “Cancel Shipment” button located inside the metabox to the right.
  3. If a shipment was successfully cancelled, the order note will display “Shipment successfully cancelled”.

Remove Stored Shipment

  1. Navigate to → WooCommerce → Orders.
  2. Navigating to the specific order and clicking the “Remove Stored Shipment” button located inside the metabox to the right.
  3. If a shipment was successfully removed, the order note will display “Shipment successfully removed”.

Modify data sent to nShift


If yo need to add, remove or edit data sent to nShift when the create shipment request is triggered, you can use the filter  ksc_create_shipment_body.

Here is an example how to add a pickup date (which is required but not provided by Klarna or nShift) if the carrier is Budcompaniett.

<?php
/**
 * Use together with Krokedil Shipping Connector pluign.
 * https://krokedil.se/produkt/krokedil-shipping-connector/
 *
 * Modify the create shipment request body. In this case we add pickupDate if the carrier is Budcompaniet.
 * Add this code to your themes functions.php file or include it in a separate functionality plugin (https://css-tricks.com/wordpress-functionality-plugins/).
 **/
add_filter('ksc_create_shipment_body', 'custom_ksc_create_shipment_body_2', 10, 2 );

function custom_ksc_create_shipment_body_2( $args, $order ) {
	// The shimpment data for the order, selected by the customer in KCO/KSA.
	$kco_kss_data  = get_post_meta( $order->get_id(), '_kco_kss_data', true );
	$shipment_data = json_decode( $kco_kss_data, true );
	
	//Get the carrier for the order.
  	$carrier = $shipment_data['delivery_details']['carrier'];
  
  	if( 'budcompaniett' === strtolower( $carrier ) ) {
		// Send the pickup date to nShift Delivery.
		$args['service']['properties']['pickupDate' ] = date("Y-m-d");
	}
	
 	return $args;
}