Skip to main content

nShift DeliveryCheckout

Our partner nShift is the market leader in delivery management solutions for ecommerce. nShift DeliveryCheckout, which is what powers Walley Checkout with delivery options, is a solution that enables the merchant to easily add new delivery options from nShift's extensive carrier library. The merchant can also easily configure business rules to handle for instance price levels for free delivery and ranking of delivery options.


How to get started πŸš€β€‹

  1. Contact Walley Merchant Services for help with setup in our test environment and for questions regarding integration with Walley Checkout.
  2. Create a nShift DeliveryCheckout configuration. Visit nShift to read more and contact nShift for questions regaring prices, configuration etc.
  3. Provide Walley Merchant Services with the nShift api-credentials (Id and Secret Id) as well as the Delivery Checkout Id and Quick Id of the sender to use. Once a DeliveryCheckout configuration is in place and properly tested in the test environment, then you are good to go. Note: Once the Quick Id has been set it must not change.
Please note

During test and development, it is possible to use the nShift DeliveryCheckout production configuration, but it is important to note, that such setup means that purchases made in the Walley test environment will create prepared shipments against your nShift production account. Ensure such prepared shipments are treated as test.

Customize delivery methods​

Walley Checkout fetches the list of available delivery methods every time the customer changes any relevant information that might lead to a change in available delivery methods, e.g. the customer changes delivery address or updates the cart. When the Checkout sends the GET request to nShift, it has some default query parameters that are always included.

Default Request Query Parameters

ParameterExplanation
currencyCurrency used for the checkout session
languageThe display language used for the checkout session. Supported language are: sv, no, fi, da, en
tocountryThe country code for the customer's current delivery address
tozipcodeThe postal code for the customer's current delivery address
cartpriceThe total price for cart
weightThe total weight for the cart, sum of all the article's weights sent in set cart request
toemailThe customer's email address
tostreetThe address for the customer's current delivery address
storetypeCustomerType for the checkout session, b2b or b2c

When requesting for available shipping methods, apart from all the parameters above, you can set custom parameters that is related to articles in the cart. This is done by adding shippingProperties to the cart object in either Initialize Checkout or Update Cart as a JSON object that will be be added in the request query parameters automatically the following way:

{
"items": [
{
"id": "2",
"description": "A bulky product",
"unitPrice": 100,
"unitWeight": 2,
"quantity": 1,
"vat": 20,
"requiresElectronicId": true,
"sku": "a unique alphanumeric code for article identification"
}
],
"shippingProperties": {
"height": 10,
"width": 20,
"isBulky": true
}
}

The following scenario would result in the following GET-request to nShift to fetch the delivery methods:

https://{UriToNShift}?currency={currency}&....&storetype={storetype}&height=10&width=20&isBulky=true
Please note

Note that the example with height, width and isBulky are just examples. Any key/value pair can be used and will be translated to query parameters accordingly.

When you create your configuration at nShift, these query parameters can be used to adjust conditions for the delivery methods as desired, e.g adjust the shipping fee based on cartprice, enable/disable an option based on storetype or isBulky.

Addons for nShift DeliveryCheckout​

Some carriers have addons that can be configured in nShift Online. For now, we do not show any of those addons in the Delivery Module. However, we do support the following addons without showing them to the customer:

  • Notification by e-mail (addon id "FCNOTIFYEMAIL")
  • Notification by sms (addon id "FCNOTIFYSMS")

If they are enabled in your configuration, they will automatically be added from the customer's profile when we create the prepared shipment. The fee for such addon should always be free since there is no chance for the customer to change it.

Extra data fields for nShift DeliveryCheckout​

Extra data fields can be added to your configuration. For now, we only support "Door code", which will appear on all your delivery options in the Delivery Module that does not have any service points.

Fallback strategy​

If, for any reason, we do not get any delivery methods from nShift, we will still let the customer complete the purchase without a selected delivery method. For that case, the delivery will always be free of charge for the customer and the delivery must be created manually after purchase.

After purchase​

When the customer has selected a delivery method and completes the purchase, Walley Checkout will create a prepared shipment at nShift that is not yet activated. When we do this we get a prepareId from nShift that we will hand over to you. This id is provided when you Aquire Checkout Information under data.shipping.pendingShipment.id.

When the package is ready to be delivered, you need to activate the delivery by sending a request to nShift with this prepareId. See nShift's documentation how to activate the prepared shipment.

There will be three scenarios that can occur for the checkout session regarding the delivery selection:

  1. We successfully received delivery methods and successfully created a prepared shipment.
  2. We successfully received delivery methods but failed to create the prepared shipment.
  3. We failed to receive delivery methods and have not been able to create a prepared shipment.
Please note

For scenario 2, the pendingShipment will not have an id (id=null). The rest of the information will be provided though, so you will be able to see where the customer intends to get his/hers packages delivered (carrier and servicePoint).

For scenario 3, the shipping object will not exist which is a signal that you must handle this manually and create a shipment for your customer based on the delivery address. Also note that the delivery will always be free of charge for the customer.

Below are examples of the JSON structure of the shipping object specific to nShift DeliveryCheckout for the three scenarios.

// Simplified Get Checkout Information response with focus on shipping and order object
{
"id": "9eec015f-4b97-44be-a711-d22f3af75069",
"data": {
"customer": {...},
...,
...,
"status": "PurchaseCompleted",
"order": {
"totalAmount": 319,
"items": [
{
"id": "11111",
"description": "Item one",
"unitPrice": 100,
"unitWeight": 1,
"quantity": 1,
"vat": 25,
"sku": "Item one sku"
},
{
"id": "222222",
"description": "Item two",
"unitPrice": 200,
"unitWeight": 2,
"quantity": 1,
"vat": 25,
"sku": "Item two sku"
},
{
"id": "Frakt",
"description": "DHL Ombud",
"unitPrice": 19,
"quantity": 1,
"vat": 25
}
]
},
"shipping": {
"provider": "Unifaun",
"carrierName": "DHL Ombud",
"carrierId": "6254453a-fc0c-414d-86b6-529c7f62d495",
"servicePointName": "PAKETBOX WILLYS HVITFELDTSPL.",
"servicePointId": "SE-987200",
"shippingFee": 19,
"shippingFeeId": "Frakt",
"pendingShipment": {
"id": "637382736786478"
}
},
...
},
"error": null
}
Please note

If updating the delivery configuration while running in production, read the section how to work with versions. The versions makes it possible to create a prepared shipment for customers that fetched delivery method with the older configurations.