nShift Checkout Adapter

Overview

The nShift Checkout adapter integrates nShift Delivery Checkout with Norce Checkout. It enables merchants to offer dynamic shipping options including home delivery, pickup points, and time slots directly within their checkout flow. Changes made in Norce Checkout are synced with nShift and vice versa. Read more on nShift Checkout docs.

Environments

There are three environments that you can use. Replace {slug} with your merchant slug.

Environment	Address
Playground	`https://{slug}.api-se.playground.norce.tech/checkout/nshift-adapter`
Stage	`https://{slug}.api-se.stage.norce.tech/checkout/nshift-adapter`
Production	`https://{slug}.api-se.norce.tech/checkout/nshift-adapter`

Getting Started as a Partner

To use the nShift Checkout adapter, you need to set up your nShift account and configure the adapter in Norce Checkout Admin.

Prerequisites

Before configuring the adapter, ensure you have the following from nShift:

Client ID and Client Secret: Create these in the nShift Portal under Settings > API Configuration > Client
Connection ID: Set up a connection in nShift Portal that defines your shipping configuration

Configuration

Add your configuration for the nShift Checkout adapter in Norce Checkout Admin. The configuration requires:

API Settings: Your nShift Client ID, Client Secret, and Connection ID
Options: Default language, currency, and locale settings
Widget Settings: Customization options for the nShift checkout widget appearance

Create Shipping

To get an nShift Checkout session with shipping options data, create a shipping using the nShift adapter.

POST /api/checkout/v1/orders/{order_id}/shippings

The nShift adapter will fetch the order, map it to nShift's format, and create a session. The response contains the Norce shipping ID, the nShift session ID, widget settings, and available shipping options data.

{
    "shippingId": "sGMVlgVNMjCDxsdJaOwmklGEpjM",
    "sessionId": "abc123-session-id",
    "selectedOptionId": "option-1",
    "settings": {
        "widgetVersion": "2",
        "theme": "nshift-theme1",
        "mode": "standard",
        "themeOverride": {
            "showLogos": true,
            "showMap": true,
            "showPickupPointInfo": true,
            "selectFirstAvailableOption": true
        }
    },
    "data": {
        "options": [
            {
                "valid": true,
                "optionId": "option-1",
                "name": "Home Delivery",
                "carrierName": "PostNord",
                "price": 49.00,
                "taxRate": 25.0,
                "deliveryTime": {
                    "earliestDate": "2024-01-15",
                    "latestDate": "2024-01-17",
                    "description": "1-3 business days"
                }
            }
        ],
        "categories": [],
        "addons": [],
        "fields": []
    }
}

Automatic Hook Registration

The adapter will register any hooks and notifications required to keep track of changes to the order, so you will not need to inform it of changes made to the order by other adapters.

The response data is designed to be passed directly to the nShift Checkout widget. Include the nShift widget scripts in your page, then create and configure the widget using the settings and data from the adapter response. For detailed widget integration instructions, see the nShift Widget documentation.

<!-- Include nShift widget scripts -->
<link rel="stylesheet" href="https://www.nshiftportal.com/checkout/widget/nshift-checkout-widget.css">
<script src="https://www.nshiftportal.com/checkout/widget/nshift-checkout-widget.js"></script>

<!-- Widget container -->
<div id="nshift-widget-container"></div>

<script>
// After calling the Create Shipping endpoint and receiving the response:
const response = /* response from POST /api/checkout/v1/orders/{order_id}/shippings */;

// Configure widget settings from the adapter response
const widgetSettings = {
    widgetVersion: response.settings.widgetVersion,
    theme: response.settings.theme,
    mode: response.settings.mode,
    themeOverride: response.settings.themeOverride,
    widthBreakpoints: response.settings.widthBreakpoints,
    resultCallback: function(result) {
        // When user selects an option, call the shipping-changed endpoint
        fetch(`/api/checkout/v1/callback/orders/${orderId}/shippings/${response.shippingId}/shipping-changed`, {
            method: 'POST',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify(result)
        });
    }
};

// Create and install the widget
const container = document.getElementById('nshift-widget-container');
const widget = nShiftCheckoutWidget.createWidget(container, widgetSettings);
widget.install();

// Load shipping options from the adapter response
widget.updateOptions(response.data);
widget.enable();
</script>

Get Shipping Session

To retrieve an existing nShift session with the latest shipping options, use the GET endpoint:

GET /api/checkout/v1/orders/{order_id}/shippings/{shipping_id}

This returns the same structure as the create endpoint, with the selectedOptionId reflecting the user's current selection. Use this response data to update the nShift widget with the latest shipping options using widget.updateOptions(response.data) as shown in the widget integration example above.

Client Side Callbacks

Required Client-Side Callback

nShift will not inform the adapter directly of all changes made through the nShift Checkout widget. When a user interacts with the widget (selects a shipping option, pickup point, time slot, or addon), the widget triggers the resultCallback function. You need to listen for this callback and call the Norce nShift Adapter API to update the order.

For more details, see the nShift widget user interaction documentation.

Listening to the resultCallback

When configuring the nShift widget, provide a resultCallback function in the widget settings. This callback is triggered whenever the user interacts with the widget. The callback receives a result object containing the user's selection:

const widgetSettings = {
    // ... other settings from adapter response
    resultCallback: function(result) {
        // The result object contains the user's selection
        if (result.valid) {
            // Selection is complete and can be used to update the order
            callShippingChanged(result);
        }
        // If result.valid is false, more user interaction is required
        // (e.g., user needs to select a pickup point)
    }
};

The result object includes these key properties:

valid: true if the selection is complete and can be used to create a shipment
sessionId: The nShift session ID (required for the shipping-changed call)
optionId: The selected shipping option ID
pickupPointId: The selected pickup point ID (if applicable)
timeSlotId: The selected time slot ID (if applicable)
addons: Array of selected addons with their prices and field values
fields: Array of field inputs (e.g., phone number, email)
totalPrice: Total price of the selected shipping option including addons

Shipping Changed

When the resultCallback is triggered with valid: true, call the shipping changed endpoint to update the Norce order with the user's selection:

POST /api/checkout/v1/callback/orders/{order_id}/shippings/{shipping_id}/shipping-changed

Request body (the selection result from the nShift widget):

{
    "sessionId": "abc123-session-id",
    "optionId": "option-1",
    "pickupPointId": "pickup-123",
    "timeSlotId": null,
    "addons": [],
    "fields": [],
    "totalPrice": 49.00
}

Automatic Updates

Automatic Background Updates

The adapter automatically handles updates when the Norce order changes. These hooks are registered automatically when creating the session, so no action is required from the partner.

Cart Changed

When items in the cart change, the adapter receives a callback and refreshes the shipping options from nShift. This ensures that shipping prices and availability are always accurate based on the current cart contents.

State Changed

When the order state changes to "accepted", the adapter automatically creates a partial shipment in nShift. This is a required step in the nShift workflow that prepares the shipment for fulfillment.

Completing the Session

As you complete your order (usually driven by a payment adapter), the nShift adapter will react to the state change and create a partial shipment in nShift. The shipping object will then contain the partialShipmentId in the tmsReference field and in the shipping attributes.

The nShift Checkout widget can be integrated into your frontend using the settings and data returned from the adapter. The widget provides a user interface for selecting shipping options, pickup points, and time slots.

For detailed widget integration instructions, see the nShift Widget documentation.

The adapter returns widget settings that can be used to configure the nShift widget:

widgetVersion: Currently "2"
theme: The styling theme (e.g., "nshift-theme1")
mode: "standard" for normal checkout, "product" for read-only product page widget
themeOverride: Customization options like showing logos, maps, and delivery times
widthBreakpoints: Responsive styling breakpoints

Remove Shipping

To remove an nShift shipping session from an order:

POST /api/checkout/v1/orders/{order_id}/shippings/{shipping_id}/remove

This will mark the shipping as removed in the Norce order.